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Intended Audience 


This manual is for programmers at all levels of experience. It covers both 
user interfaces of the debugger: 


¢ The VMS DECwindows interface, for workstations 


¢ The command interface, for terminals and workstations 


The debugger can be used with most VAX languages (language support 
is summarized in Appendix E). This manual emphasizes usage that is 
common to all or most languages. For additional information that is 
specific to a particular language, see the documentation furnished with 
that language. 


Note that you can use the VMS Debugger only to debug code in user mode. 
You cannot debug any code in supervisor, executive, or kernel modes. 

If you need to debug code in other than user mode, refer to the VMS 
Delta/XDelia Utility Manual, which describes the VMS DELTA/XDELTA 
Utility. 





Document Structure 
This manual is organized in two parts: 


¢ Part I introduces the debugger’s DECwindows interface. Additional 
information about the DECwindows interface is available through 
online help, as explained in Chapter 1. 


¢ Part II completely describes the debugger’s command interface: 
— Chapter 2 introduces the command interface. 


— The remaining chapters provide task-oriented and conceptual 
information. To simplify the discussions, many details about the 
debugger commands are not included in these chapters. 


— The command dictionary provides complete information about the 
debugger commands. 


— The appendixes provide reference details about specific subjects. 





Associated Documents 


General information about the VMS DECwindows interface is available in 
the VMS DECwindows User’s Guide. 


Information about compiling and debugging that is specific to a particular 
language is available in the documentation furnished with that language. 


Information about VAX assembly-language instructions and the VAX 
MACRO assembler is available in the VAX MACRO and Instruction Set 
Reference Manual. 
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Information about the linking of programs and about shareable images is 
available in the VMS Linker Utility Manual. 





Conventions 


The following conventions are used in this manual: 


mouse 


MB1, MB2, MB3 


Ctrl/x 


PF1 x 


[] 


red ink 
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The term mouse is used to refer to any pointing 
device, such as a mouse, a puck, or a stylus. 


MB1 indicates the left mouse button, MB2 indicates _ 
the middie mouse button, and MBS indicates the right 
mouse button. (The buttons can be redefined by the 
user.) 


A sequence such as Cirl/x indicates that you must 
hold down the key labeled Ctrl while you press 
another key or a pointing device button. 


A sequence such as PF1 x indicates that you must 
first press and release the key labeled PF1, then 
press and release another key or a pointing device 
button. 


In examples, a key name is shown enclosed in a box 
to indicate that you press a key on the keyboard. (In 
text, a key name is not enclosed in a box.) 


In examples, a horizontal ellipsis indicates one of the 
following possibilities: 


¢ Additional optional arguments in a statement 
have been omitted. 


¢ The preceding item or items can be repeated one 
or more times. 


¢« Additional parameters, values, or other 
information can be entered. 


A vertical ellipsis indicates the omission of items from 
a code example or command format; the items are 
omitted because they are not important to the topic 
being discussed. 


In format descriptions, parentheses indicate that, if 
you choose more than one option, you must enclose 
the choices in parentheses. 


In format descriptions, brackets indicate that whatever 
is enclosed within the brackets is optional; you can 
select none, one, or all of the choices. (Brackets are 
not, however, optional in the syntax of a directory 
name in a file specification or in the syntax of a 
substring specification in an assignment statement.) 


Red ink indicates information that you must enter from 
the keyboard or a screen object that you must choose 
or click on. 


For online versions of the book, user input is shown in 
bold. 


boldface text 


UPPERCASE TEXT 


numbers 


Preface 


Boldface text represents the introduction of a new 
term or the name of an argument, an attribute, or a 
reason. 


Boldface text is also used to show user input in online 
versions of the book. 


Uppercase letters indicate that you must enter a 
command (for example, enter OPEN/READ), or they 
indicate the name of a routine, the name of a file, the 
name of a file protection code, or the abbreviation for 
a system privilege. 

Unless otherwise noted, all numbers in the text are 
assumed to be decimal. Nondecimal radixes—binary, 
octal, or hexadecimal—are explicitly indicated. 
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Part! Using the Debugger: DECwindows Interface 


This part introduces the VMS debugger’s DECwindows interface. Additional 
information about the DECwindows interface is available through online help. 


For information about the debugger’s command interface, see Part Il. 





1 Introduction to the Debugger: DECwindows Interface 


This chapter introduces the VMS Debugger’s DECwindows interface and 
provides enough information to get you started. For information about the 
debugger’s command interface, see Part II of this manual, which starts 
with Chapter 2. 


The following information is provided in this chapter: 
e An overview of the debugger’s main features 


e Instructions to prepare your program for debugging and start a 
debugging session 


e An overview of the debugger windows and menus 
e A-sample session to get you started with the debugger | 


¢ Introductions to most of the functions you can perform with the 
debugger. 


Many topics are covered very briefly. The documentation for the debugger’s 
DECwindows interface consists mainly of online help, and this chapter 
includes numerous references to specific topics in the debugger’s Help 
menu, in the main window. The debugger’s online help system is explained 
in Section 1.5.1. 


To use this chapter most effectively, read it while running the debugger on 
your workstation. 


It is assumed that you are familiar with the general DECwindows 
environment as described in the VMS DECwindows User’s Guide— 
that is, you should know how to use the pointer cursor and keyboard 
to manipulate windows, menus, dialog boxes, online help, and so on. 


If you are already familiar with the debugger’s command interface, 
including how to invoke the debugger from DCL level (as described in 
Part II of this manual), you can start with Section 1.2.3. 





1.1 Overview of the Debugger 


The debugger is a tool that helps you locate run-time programming or logic 
errors, also known as bugs. You use the debugger with a program that 
has been compiled and linked successfully but does not run correctly. For 
example, the program might give incorrect output, go into an infinite loop, 
or terminate prematurely. 


You locate errors with the debugger by observing and manipulating your 
program interactively as it executes. The debugger enables you to do the 
following tasks: 


¢ Control the program’s execution—start the program, stop at points of 
interest, resume execution, and so on 
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e Trace the execution path of the program 

¢ Monitor changes in variables and other program entities 

¢ Monitor exception conditions and language-specific events 

e Examine and modify the values of variables, or force events to occur 


e In some cases, test the effect of modifications without having to edit 
the source code, recompile, and relink 


These are the basic debugging techniques. After you are satisfied that 
you have found the error in the program, you can edit the source code and 
compile, link, and execute the corrected version. 


As you use the debugger and its documentation (particularly the online 
help) you will discover variations on the basic techniques. You can also 
tailor the debugger for your own needs. 


The debugger is a symbolic debugger. You can specify variable names, 
routine names, and so on, precisely as they appear in your source code. 
You do not need to specify memory addresses or VAX registers when 
referring to program locations, although you can, if you want. 


You can use the debugger with the following VAX languages: Ada, BASIC, 
BLISS, C, COBOL, DIBOL, FORTRAN, MACRO-32, Pascal, PL/I, RPG II, 
and SCAN. 


The debugger recognizes the syntax, data typing, operators, expressions, 
scoping rules, and other constructs of a given language. If your program is 
written in more than one language, you can change the debugging context 
from one language to another during a debugging session. 





1.2 Starting a Debugging Session 


The usual way to invoke the debugger from a DECterm window is as 
follows: 


1 Compile and link the program with the /DEBUG DCL command 
qualifier 


2 Make sure that the debugging configuration (default or multiprocess) 
is appropriate for the kind of program you are going to debug 


3 Invoke the debugger by entering the DCL RUN command 


These steps are explained in the following sections. Additional options for 
invoking the debugger are discussed in Section 1.6. 


1.2.1. Compiling and Linking a Program to Prepare for Debugging 


Before you can use the debugger, you must compile and link the modules 
(compilation units) of your program as explained in this section. The 
following example shows how to compile and link a Pascal program, 
consisting of a single compilation unit named EIGHTQUEENS, before 
using the debugger. 


1.2.2 
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Note: The /DEBUG and /NOOPTIMIZE qualifiers are compiler command 


defaults for some languages. These qualifiers are used in the 
example for emphasis. 


$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
$ LINK/DEBUG EIGHTQUEENS 


The /DEBUG qualifier on the compiler command (PASCAL in this 

case) directs the compiler to write the symbol information associated 
with EIGHTQUEENS into the object module, EIGHTQUEENS.OBJ, in 
addition to the code and data for the program. This symbol information 
enables you to use the names of variables and other symbols declared 

in EIGHTQUEENS in debugger dialog boxes and commands. If your 
program has several compilation units, you must compile each unit whose 
symbols you want to reference with the /DEBUG qualifier. 


Some compilers optimize the object code to reduce the size of the program 
or to make it run faster. In such cases you should compile your program 
with the /NOOPTIMIZE command qualifier (or equivalent). Otherwise, the 
contents of some program locations might be inconsistent with what you 
would expect from viewing the source code. 


The /DEBUG qualifier on the LINK command causes the linker to include 
all symbol information that is contained in EIGHTQUEENS.OBJ in the 
executable image. The qualifier also causes the VMS image activator 

to start the debugger at run time. If your program has several object 
modules, you need to specify those modules in the LINK command, for 
most languages. 


Establishing the Debugging Configuration 


Before invoking the debugger as explained in Section 1.2.3, check that the 
debugging configuration is appropriate for the kind of program you are 
going to debug. 


You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or 
several processes, respectively. The configuration depends on the current 
definition of the logical name DBG$PROCESS. Thus, before invoking the 
debugger, enter the DCL command SHOW LOGICAL DBG$PROCESS to 
determine the definition of DBG$PROCESS. 


Most of this chapter covers programs that run in only one process. For 
such programs, DBG$PROCESS either should be undefined, as in the 
following example, or should have the value DEFAULT: 


S$ SHOW LOGICAL DBGSPROCESS 
SSHOW-S-NOTRAN, no translation for logical name DBGSPROCESS 


If DBG$PROCESS has the value MULTIPROCESS, and you want to 
debug a program that runs in only one process, enter the following 
command: 


S$ DEFINE DBGSPROCESS DEFAULT 


For more information about multiprocess debugging, see Section 1.5.15. 
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1.2.3. Invoking the Debugger 


1-4 


After you compile and link your program and establish the appropriate 
debugging configuration, you can then invoke the debugger. To do so, enter 
the DCL command RUN, specifying the executable image of your program 
as the parameter. For example, enter the following command to debug the 
program EIGHTQUEENS: 


$ RUN EIGHTQUEENS 


By default, the debugger comes up in the following three windows, 
arranged as shown in Figure 1-1: 


e The main window. 


e The predefined source window SRC, which shows the source code of 
the module you are debugging. The numbers shown at the left of the 
source code are compiler-generated line numbers, as they might appear 
in a compiler-generated listing file. 


e¢ The predefined output window OUT, which displays the debugger’s 
output. For example, it shows the value of a variable that you are 
examining. 
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Figure 1-1 Debugger Windows at Startup 
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HI 


: INTEGER; 

A : ARRAY[1..8] OF BOOLEAN; 
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X 
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: ARRAY[1..8] OF INTEGER; 
afe : BOOLEAN; K: INTEGER; 





PROCEDURE Print; 
BEGIN (* Print *) 
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Windows SRC and OUT are two examples of the kinds of debugger 
windows you can use to capture and display different types of data. 


The message that is displayed in window OUT at debugger startup 
indicates that this debugging session is initialized for a Pascal program 
and that the name of the main program unit (the module containing the 
image transfer address) is EIGHTQUEENS. The initialization sets up 
language-dependent debugger parameters. 


By default, the boxed line in window SRC indicates where execution is 
currently suspended. When you start a debugging session, the debugger 
usually suspends execution at the beginning of the main program (line 1, 
in this example). For Ada programs and certain other kinds of programs, 
execution is initially suspended at the beginning of initialization code, 
before the main program, so that you can choose to execute that code 
under debugger control. To execute to the beginning of the main program 
in such cases, click on the Go button in the main window. See your 
language documentation for more information. 


You can now use the debugger to start execution, set breakpoints, 
examine variables, and so on, as explained in Section 1.4 and Section 1.5. 
Section 1.3 gives an overview of the debugger’s windows and menus. 


1.3 


1.3.1 
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Debugger Windows and Menus 


The debugger windows consist of a main window and several predefined 
windows that capture and display different kinds of data. The following 
sections briefly describe these windows and the pop-up menu, which is 
available from any debugger window. 


For more information, choose Overview from the Help menu, then choose 
Debugger Windows and Menus. 


Debugger Main Window 


The debugger’s main window (see Figure 1—2) includes a menu bar, a 
status region, and four buttons that are labeled Go, Step, Examine, and 
Stop. 


Figure 1-2 Debugger Main Window 
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¢ Figure 1-8 shows the menus on the main window’s menu bar. 
Figure 1—4 and Figure 1—5 show the submenus of the Data and 
Customize menus, respectively. Table 1-1 summarizes the functions of 
these menus and submenus. 


e Table 1—2 summarizes the type of information displayed in the status 
region fields and the functions of the associated arrow buttons. 


¢ Table 1-3 summarizes the functions of the Go, Step, Examine, and 
Stop buttons. 


Note that the functions of the Go, Step, and Examine buttons can also be 
performed through other means, such as the pop-up menu, Control menu, 
or Data menu. 
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Figure 1-3 Main Window Pull-Down Menus 
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Figure 1-4 Data Menu and Submenus 
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Figure 1-5 Customize Menu and Submenus 
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Main Window Pull-Down Menus 


Description 


End the debugging session. 


Copy text to the clipboard, or paste text from the clipboard to a 
debugger dialog box or the COMMAND box. 


Start, stop, and monitor the execution of your program under debugger 
control. For example: execute to the next line or to the next 

VAX assembly-language instruction; set breakpoints, tracepoints, 

and watchpoints; call a routine. For vectorized programs, force 
synchronization between the scalar and vector processors. 


Display or manipulate data that is associated with your program. For 
example: examine variables and arbitrary program locations; assign 
new values to variables; evaluate language expressions; control access 
to variable names, routine names, and other symbols; manipulate 
multiprocess programs and Ada tasking programs. Note that the Tasks 
menu item is dimmed unless you are debugging a VAX Ada program. 


Tailor your debugging environment and establish default conditions. 
For example: create and manipulate debugger windows; change the 
programming language context; establish defaults for manipulating data 
and for accessing symbols; open the COMMAND box to access the 
debugger’s command interface. 


Obtain conceptual and task-oriented information about the debugger. 
This is an alternative to obtaining context-sensitive help on individual 
items that are displayed on the screen (menus, buttons, dialog boxes, | 
and so on). 
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Table 1~2 Main Window Status Region 


Label Description 


Current Entity Identifies the last entity that was examined or whose value was 
changed (for example, a variable or a code location). Use the 
arrow buttons to display consecutive logical entities—for example, 
consecutive elements of an array variable. 


Call Frame Identifies the routine that the debugger uses as reference when 
displaying source code in the source window or instructions in 
the instruction window, or when searching for symbols that are 
associated with your program (variable names, routine names, 
and so on). Use the arrow buttons to reset the reference to 
another call frame on the call stack. 


Visible Process For a one-process program, identifies the process that is 
running the program. For a multiprocess program, identifies 
the process that is currently the context for entering process- 
specific commands. Use the arrow buttons to reset the visible 
process to another process that is under debugger control. 


Table 1-3 Main Window Buttons 


Button Description 
Go Start execution from the current program location. 
Step Execute the program one step unit of execution. By default, this is one 


executable line of source code. 


Examine Display the value of a variable or other entity whose name is selected in 
a window, or the value of the entity last examined, if no text was selected. 


Stop Interrupt program execution or a debugger operation without ending the 
debugging session. 


1.3.2 Debugger Predefined Windows 


The debugger provides the following predefined windows that you can use 
to capture and display different kinds of data: 


SRC, the predefined source window 

OUT, the predefined output window 

AUTO, the predefined automatic window (a special output window) 
INST, the predefined instruction window 

REG, the predefined register window 


Of these windows, only SRC and OUT are displayed, by default, at 
debugger startup. | 


The basic features of the predefined windows are described in the next 
sections. You can change certain characteristics of these windows, such as 
buffer size or window attributes. You can also create additional windows 
similar to the predefined windows. For more information, choose Overview 
from the Help menu, then choose Debugger Windows and Menus, then 
choose Debugger Predefined Windows (SRC, OUT, INST, REG, AUTO). 
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Predefined Source Window (SRC) 


You can use window SRC to display source code in two basic ways: 


e By default, SRC automatically displays the source code for the module 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 


¢ In addition, you can use SRC to display the source code for any part of 
your program. 


The name of the module whose source code is displayed is shown at the 


right of the window name, SRC. The numbers displayed at the left of the 
source code are the compiler-generated line numbers, as they might appear 
in a compiler-generated listing file. 


The next paragraphs describe the behavior of SRC when it is displaying 
the current location. Section 1.5.5 explains how to display source code in 
arbitrary locations. 


As you execute the program under debugger control, window SRC is 
updated automatically whenever execution is suspended. The boxed line 
indicates the next line to be executed. 


If the debugger cannot locate source lines for the routine in which 
execution is suspended (because, for example, the routine is a run-time 
library routine), it tries to display source lines in the next routine down 
on the call stack for which source lines are available. If the debugger can 
display source lines for such a routine, it issues the following message: 


SDEBUG-I-SOURCESCOPE, Source lines not available for .0O\%PC. 
Displaying source in a caller of the current routine. 


In such cases, the boxed line in the source window identifies the line to 
which execution returns after the routine call. Depending on the source 
language and coding style, this might be the line that contains the call 
statement or the next line. 


If your program was optimized during compilation, the source code 
displayed in window SRC might not always represent the code that is 
actually executing. The predefined instruction window INST is useful in 
such cases, because it shows the exact VAX instructions that are executing. 
See Section 1.3.2.4. 


1.3.2.2 Predefined Output Window (OUT) 


Window OUT is a general purpose output window. By default, it displays 
the following information: 


e Any debugger output that is not directed to windows SRC, INST, or 
AUTO. For example, if window INST is not displayed or does not have 
the instruction attribute, any output that would otherwise update 
window INST is displayed in window OUT. 


e Debugger diagnostic messages. Messages with a severity level greater 
than I (informational) are also displayed in a message box (see 
Section 1.5.2). 
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Note that, when displaying variable names, routine names, and other 
symbolic address expressions, the debugger adds a path name prefix to 
the name. The path name prefix identifies the nesting program elements 
in which the entity was declared in the program. For example, if you 
examined a variable K, whose value was 26, in routine SWAP of module 
SWAP_PACK, the debugger might display the following output: 


SWAP_PACK\SWAP\K: 26 
In this case, SWAP_PACK\SWAP\ is the path name prefix. 


In most cases, you do not need to include a path name prefix when 
specifying symbolic address expressions (see Section 1.5.10.2). 


1.3.2.3 Predefined Automatic Window (AUTO) 
Window AUTO is an automatically updating window that can be used 
instead of window OUT to display the output from the following dialog 
boxes, which are accessible from the Data menu: 


Examine Variable 
Examine Address or Register 
Language Expressions 


Window AUTO is created when you first click on the Display button in any 
one of these dialog boxes. Thereafter, AUTO remains open until you close 
it. 


AUTO includes a debugger command list in its definition. Every time the 
debugger gains control, AUTO is updated with the output of that command 
list. 


When AUTO is created, its command list consists of the Examine or 
Evaluate command that was generated when you clicked on the Display 
button, and it displays the output of that command. 


Subsequently, every time you click on the Display button in any of the 
three dialog boxes listed, the debugger appends the new command 
generated to the current command list and updates AUTO to display 
the output from the entire command list. 


1.3.2.4 Predefined Instruction Window (INST) 
Window INST displays the decoded VAX assembly-language instruction 
stream of your program. This is the exact code that is executing, including 
the effects of any compiler optimization. 


You can use INST in two basic ways: 


e By default, INST automatically displays the instructions for the 
routine in which execution is currently suspended. This enables you to 
quickly determine your current debugging context. 


e In addition, you can use INST to display the instructions for any part 
of your program. 


By default, INST is not displayed on the screen. To open INST, choose 
Window Setups from the Customize menu. Clicking on a window layout 
of the Window Setups submenu enables you to place INST next to either 
window SRC or window REG. 
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If your program was optimized during compilation, the window layout that 
places windows SRC and INST side by side enables you to readily compare 
the source code and the decoded instruction stream. 


See Section 1.5.6 for more information about displaying instructions. 


1.3.2.5 Predefined Register Window (REG) 


Window REG displays the current values, in hexadecimal format, of the 
VAX general registers (RO to R11, AP, FP, SP, PC), the four condition code 
bits (C, V, Z, and N) of the processor status longword (PSL), and as many 
of the top stack values as can be displayed through the window. 


The values contained in the registers are updated each time the debugger 
gains control. 


By default, REG is not displayed on the screen. To open REG, choose 
Window Setups from the Customize menu. Clicking on the third layout 
of the Window Setups submenu enables you to place REG next to window 
INST. 


1.3.3 Using the Pop-Up Menu 
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The debugger’s pop-up menu (see Figure 1-6) enables you to perform 
several common operations without having to pull down a menu in the 
main window. 


Figure 1-6 Pop-Up Menu Over Source Window 
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For an explanation of the pop-up menu items, use the pop-up menu’s 
context-sensitive help (see Section 1.5.1). All pop-up menu functions can 
also be performed through other means. 


To use the pop-up menu, proceed as follows: 
1 Position the pointer cursor within a debugger window. 


2 Press and hold MB2 to display the pop-up menu, then drag to the 
desired menu item and release MB2. 
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Note that the behavior of the Examine, Evaluate, and Set Break menu 
items depends on whether you selected text before invoking the pop-up 
menu. 


1.4 Getting Started with the Debugger 


This section walks you through the following basic steps with a sample 
program, EIGHTQUEENS. The complete source code for the program is 
shown in Section 1.7. 


, 
2 
3 
4 


4) 
6 


Set a breakpoint to suspend execution at a routine call statement. 
Execute the program to the breakpoint. 
Execute the program into the called routine. 


While execution is suspended within the routine, display the current 
value of a variable. 


Assign another value to the variable. 


Display source code in the calling routine. 


Figure 1—7 shows the source window, SRC, at debugger startup. Execution 
is suspended at line 1 (the boxed line) of module EIGHTQUEENS. 


Figure 1-7 Source Window at Debugger Startup 
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PROCEDURE Print; 
BEGIN (4% Print *) 
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1.4.1 Setting a Breakpoint 


In this section, a breakpoint is set on line 60 of module EIGHTQUEENS. 
Line 60, which is hidden below the window border in Figure 1—7, contains 
a call to routine TRYCOL (see Figure 1-8). 


Proceed as follows: 


1 


Scroll the source window to display line 60. 
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2 Double click on any part of line 60. When setting a breakpoint, you 
can select any portion of a line in the source window. For example, 
you could select the number 60, as shown in Figure 1-8, or the word 
TRYCOL. The breakpoint would be set on line 60 in either case. 


3 Choose Set Break from the pop-up menu. 


A breakpoint is now set on line 60—specifically, at the beginning of line 
60, before the call to routine TRYCOL is executed. 


Figure 1-8 Setting a Breakpoint with the Pop-Up Menu 


VAX DEBUG: SRC - module EIGHTQUEENS AIF] 
File Edit Commands 
523 Examine 2 
53: BEGIN (* Eightqueens *) 
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5S: ALI] := TRUE; Step Into Routine 
56: FOR I := 2 TO 16 DO : 
57: B[I] := TRUE; Step Over Routine 
58: FOR I := -7 TO 7 DO Step To Return 
59: C[I] := TRUE; Step By Instruction 


Trycol(i); Se etal 
61:  WRITELN; tep By Line 


62: END. (* Eightqueens *) o 
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1.4.2 Executing the Program to the Breakpoint 
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To execute the program from the current location (line 1) to the breakpoint 
at line 60, click on the Go button in the main window. 


When execution reaches the breakpoint, the source window is updated 
automatically: line 60 is boxed, indicating that execution is now suspended 
at the call statement to routine TRYCOL (see Figure 1-9). 


Whenever the source window is updated as a result of program execution, 
the boxed line indicates the line to be executed next. 


Figure 1-9 Execution Suspended at Line 60 


VAX DEBUG: SRC — module EIGHTQUEENS 
File Edit Commands 


: BEGIN (* Eightqueens *) 
FOR I := 1 TO 8 DO 
A[I} := TRUE; 

FOR I := 2 TO 16 DO 


BCI] := TRUE; 
FOR I := -? TO ? DO 
C{I] := TRUE; 
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1.4.3. Executing the Program into a Called Routine 


While execution is suspended at line 60, at the call statement to routine 
TRYCOL, choose Step Into Routine from the pop-up menu to execute the 
program one step unit into the routine (see Figure 1-10). 


After this Step command has been entered, the source window is updated, 
showing that execution is now suspended at line 36, within routine 
TRYCOL (see Figure 1-11). 


The Step command is used in this section and the next to execute the 
program one source line at a time. Note that, in this mode of operation, 
the Step command executes one or more executable lines at a time, 
skipping over any other lines. Executable lines are those for which 
instructions were generated by the compiler. 


Figure 1-10 Stepping into a Called Routine 
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YaAX DEBUG: SRC —- module EIGHTQUEENS 
File Edit Commands 


C[I-J] := TRUE; 
END; (* Removequeen *) 


BEGIN (* Trycol 4) 


I := I+1; 
Safe := A[I] AND B[I+J] AND C[I-J]; 
IF Safe THEN 
BEGIN 
Setqueen; 





1.4.4 Displaying the Current Value of a Variable 


The value of the Boolean variable SAFE is obtained in this section. It is 
obtained after the assignment statement at line 39, in routine TRYCOL, 
has been executed (see Figure 1-11). 
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To execute the program from the current location at line 36 past line 39 
(for example, to line 42), click on the Step button repeatedly until line 42 
is boxed (see Figure 1-12). 


To display the current value of the variable SAFE, proceed as follows: 


1 Double click on the word SAFE in the source window to select that 
word. 


2 Choose Examine from the pop-up menu. 


The value of SAFE (True) is now displayed in window OUT. The 
debugger displays the variable name using its full path name 
(EIGHTQUEENS\ SAFE), indicating that SAFE is declared in module 
EIGHTQUEENS. 


Note that the Current Entity field in the main window is now updated to 
identify the last entity that was examined, namely the variable SAFE. 


Figure 1-12 Examining a Selected Variable with the Pop-Up Menu 
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1.4.5 Assigning a Value to the Variable 


Assume that the variable SAFE is still selected in the source window. 
To change the value of SAFE from True to False, proceed as follows (see 
Figure 1-13): 


1 


3 


Choose Variables from the Data menu in the main window, then choose 
Deposit into Variable... from the submenu. 


When the Deposit into Variable dialog box is displayed, note that the 
selected word, SAFE, fills the Variable text-entry field. Thus, you do 
not have to enter the variable name from the keyboard. 


Enter the word False in the Language Expression field. This is the 
value to be assigned to (deposited into) the variable. 


Click on OK or Apply. 


Variable SAFE now has the value False. You can verify this by choosing 
Examine from the pop-up menu. 


Figure 1-13 Assigning a Value to a Variable 
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1.4.6 Displaying Source Code for the Calling Routine 
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By default, the source window shows the source code for the routine in 
which execution is suspended, and the name of the routine is identified in 
the Call Frame field of the main window. 


In this example, execution is currently suspended within routine TRYCOL 
of module EIGHTQUEENS. The Call Frame field in Figure 1-12 displays 
the routine path name, EIGHTQUEENS\ TRYCOL. 


The number 0 in the Call Frame field indicates that the routine whose 
source code is displayed is the routine at the top of the call stack (where 
execution is suspended). 


If, as in this example, execution is suspended within a called routine, you 
can display the source code for the calling routine by clicking once on the 
Call Frame down-arrow button. 


Clicking once displays the source code for routine EIGHTQUEENS (the 
main program), as shown in Figure 1-14. The boxed line identifies the line 
where execution will continue in that routine (line 61, which follows the 
call statement). The Call Frame field now displays the number 1, followed 
by the name of that routine. The number indicates the level, relative 

to the top of the call stack (level 0), of the routine whose source code is 
displayed. 


Figure 1-14 Displaying Source Code in the Calling Routine 
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In general, clicking on the Call Frame arrow buttons enables you to 
display the source code for any routine up or down the call stack. 


A Call Frame arrow button that is dimmed indicates that the scope 
reference is at the end of the call stack. 
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1.5 Using the Debugger 


The remaining sections of this chapter explain how to use the debugger to 
perform basic functions. After an introduction, most sections point to an 
online help topic for additional information. 


1.5.1. Displaying Online Help About the Debugger 


Note: When you first invoke the debugger’s online help system, it might 
take up to a minute to display the first help topic. Subsequent 
help topics are displayed within a few seconds after you request 
them. 


Three kinds of online help about the debugger and debugging are available 
during a debugging session: 


Context sensitive help, which is available for any item in a debugger 
window, menu, or dialog box. 


Conceptual and task-oriented help, which consists of an introductory 
help topic named Overview and several subtopics on specific subjects. 


Help about the debugger’s command interface, which is available 
through the COMMAND box. 


The technique for displaying each kind of online help is described in the 
following sections. 


1.5.1.1 Displaying Context-Sensitive Help 
Context-sensitive help about the debugger is available for any item in a 
debugger window, menu, or dialog box. 


To display context-sensitive help: 


1 
2 
3 
4 


Point to an item. 

Press and hold the Help key. 

Click on either MB1, MB2, or MB3. 
Release the Help key. 


Context-sensitive help for dialog boxes is structured in the following way: 


The same help text is displayed for any location of the pointer cursor 
within a dialog box. 


The introductory help text describes how to use the dialog box for a 
typical operation. 


In most cases, a separate additional topic is devoted to each item in 
the dialog box (button, menu, and so on). These topics are listed in the 
order that the items they describe appear in the dialog box, from top 
to bottom. 


Other topics provide task-oriented and conceptual discussions, where 
applicable. 
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When using context-sensitive help, you should also display the Overview 
help topic and look for related information in the list of additional topics. 


1.5.1.2 Displaying the Overview Help Topic and Subtopics 


The Overview help topic and subtopics provide conceptual and task- 
oriented help about the debugger and debugging. These topics supplement 
the information that is available through context-sensitive help. 


To display the Overview topic, use any one of the following techniques: 
e Choose Overview from the Help menu in the main window. 


e Ensure that a debugger window has the input focus, then press and 
release the Help key. 


¢ Choose Go To Overview from the View menu of a debugger help 
window. 


Then, to obtain information about a particular subject, choose a topic from 
the list of additional topics. 


1.5.1.3. Displaying Help About the Debugger’s Command Interface 


Help about the debugger’s command interface is available through the 
COMMAND box. 


¢ To open the COMMAND box, choose Show Command... from the 
Customize menu. 


e¢ To list the help topics, enter the command HELP at the DBG> prompt. 


e For an explanation of the command-interface help system, enter the 
command HELP HELP. 


1.5.2 Debugger Diagnostic Messages 


1-20 


Debugger diagnostic messages include numerous informational messages 
(severity level I) that provide feedback during a debugging session. (For 
an explanation of severity levels, choose Overview from the Help menu, 
then choose Debugger Diagnostic Messages.) 


To reduce the time involved in acknowledging informational messages, 
only those debugger messages that have severity levels of W, E, or F are 
displayed in a message box. 


You can get context-sensitive help on any debugger message that is 
displayed in a message box. 


By default, all debugger messages (including those of severity level I) 
are displayed in window OUT. Thus, debugger messages of severity level 
greater than I are displayed both in a message box and in window OUT. 


Messages displayed in a message box show only the message text. 
Messages displayed in window OUT show the message text, identifier, 
severity, and facility. 
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1.5.3 Interrupting Program Execution and Aborting Debugger Operations 


To interrupt program execution during a debugging session, click on 
the Stop button in the main window. This is useful if, for example, the 
program is in an infinite loop. 


To abort a debugger operation that is in progress, click on the Stop 
button in the main window. This is useful if, for example, the debugger is 
displaying a long stream of data. 


Clicking on the Stop button does not end the debugging session. Clicking 
on the Stop button when the program is not running or when the debugger 
is not performing an operation has no effect. 


1.5.4 Ending a Debugging Session 


SDEBUG-I-EXITSTATUS, 


To end a debugging session, choose either Exit or Quit from the File menu 
in the main window. 


If your program has application-declared exit handlers, Exit executes these 
handlers. Quit gives you the option of executing application-declared exit 
handlers (a dialog box is displayed in such cases). 


Unless you are debugging a multiprocess program, you can also end the 
debugging session by choosing Exit or Quit from any debugger window 
(not just the main window). 


For multiprocess programs, choosing Exit or Quit from a debugger window 
other than the main window has the following effect: 


e Ifthe window is not process specific, terminates the visible process 


e Ifthe window is process specific, terminates the process associated 
with that window 


The following message, displayed in the output window during a debugging 
session, indicates that your program has completed normally: 


is ’S%SYSTEM-S-NORMAL, normal successful completion’ 


If you want to continue debugging after seeing this message, it is usually 
best to end the session and start a new one. You can restart execution 
from within the debugging session (by choosing Go... from the Control 
menu and then specifying a location in the Go dialog box). However, this 
technique can produce unexpected results if, for example, some variables 
have different values from when you first ran the program. 


1.5.5 Displaying Source Code 


By default, window SRC automatically displays the source code for the 
module in which execution is currently suspended. 
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In addition, window SRC has the source attribute by default. Therefore, 
you can also use SRC to display the source code for any part of your 
program (if source code is available for display): 


e You can display the source code for any routine on the call stack by 
clicking on the Call Frame arrow buttons in the main window. 


The number shown in the Call Frame field indicates the relative level 
of the routine on the call stack. Call frame 0 denotes the routine at 
the top of the call stack, where execution is suspended. Call frame 1 
denotes the calling routine, and so on. 


e You can display arbitrary source lines in any module by choosing View 
Source... from the Commands menu of window SRC. 


e You can display the source line associated with a code location (for 
example, a routine declaration) by choosing Examine Code... from the 
Code submenu of the Data menu. 


After manipulating the contents of window SRC, you can display the 
location at which execution is suspended by choosing View Current 
Location from the pop-up menu. 


If the debugger cannot locate source lines for display, it issues a diagnostic 
message. 


For more information, choose Overview from the Help menu, then choose 
Displaying Source Code. 


1.5.6 Displaying Decoded VAX Instructions 
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By default, window INST automatically displays the decoded instruction 
stream for the routine in which execution is currently suspended. 


If window INST has the instruction attribute, it is also updated by any 
command that you enter to display instructions. If no window has the 
instruction attribute, the output of such commands is directed at window 
OUT. Note that opening window INST through the Window Setups 
submenu of the Customize menu automatically assigns the instruction 
attribute to that window. 


You can display instructions in window INST as follows: 


e You can display the instruction stream for any routine that is on the 
call stack by clicking on the Call Frame arrow buttons in the main 
window. 


e You can display the instructions that are associated with a code 
location (for example, a routine declaration) by choosing View 
Instructions from the Commands menu of window INST, or by choosing 
Examine Code... from the Code submenu of the Data menu. 


When you choose Examine Code..., you have the option of displaying 
detailed information about the instruction operands. 


After manipulating the contents of window INST, you can display the 
location at which execution is suspended by choosing View Current 
Location from the pop-up menu. 
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For more information, choose Overview from the Help menu, then choose 
Displaying Decoded VAX Instructions. 


1.5.7. Specifying Address Expressions in Dialog Boxes 


Several dialog boxes (for example, the Break dialog box) require you to 
enter an address expression. An address expression is an entity that 
denotes a memory address or a register. Do not confuse an address 
expression with a language expression, which denotes a value (see 
Section 1.5.9.4). 


The debugger is a symbolic debugger. Therefore, although you can specify 
a memory address or register directly in a dialog box, you usually specify 
symbolic address expressions. These include routine names, variable 
names, program labels, and source line numbers. The debugger associates 
a symbolic address expression with a unique memory address, range 

of addresses, or register. The debugger also recognizes the compiler- 
generated type that is associated with a symbolic address expression. 


Address expressions are associated with either code (VAX assembly- 
language instructions) or data. The kind of address expression you need 
to specify in a dialog box depends on the action you are about to perform 
and is indicated in the help text for that dialog box. For example, when 
setting a breakpoint, you specify an address expression that is associated 
with code; when setting a watchpoint, you specify an address expression 
that is associated with data (a variable name, in most cases). 


You can fill the Address Expression field of a dialog box in two ways: 


¢ By selecting text in a window. If you select the text before you open 
the dialog box, the text is automatically inserted in the Address 
Expression field. 


e By entering text directly from the keyboard. 


The help text for a dialog box explains the conventions for filling the 
Address Expression field. 


For more information, choose Overview from the Help menu, then choose 
Specifying Address Expressions. 


1.5.8 Controlling and Monitoring Program Execution 
This section explains how to perform the following tasks: 
e Start or resume program execution 


e Execute the program to the next source line, instruction, or other step 
unit 


¢ Use breakpoints to suspend execution at points of interest 


e Use tracepoints to trace the execution path of your program through 
specified locations 


e Use watchpoints to monitor changes in the values of variables 
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To determine where execution is suspended at any time during a 
debugging session, use the techniques described in Section 1.5.5 and 
Section 1.5.6. You can also choose Call Stack... from the Data menu to 
display the sequence of routine calls that are currently active on the call 
stack and to obtain detailed information about the call stack. 


1.5.8.1 Starting or Resuming Program Execution 


Use the Go command to start or resume program execution. 


To start execution from the current location, click on the Go button in the 
main window. 


To start execution from another location, choose Go... from the Control 
menu and specify the location in the Go dialog box. 


After it is started with the Go command, program execution continues 
until one of the following events occurs: 


e The program completes execution 
e A breakpoint is reached 

e A watchpoint is activated 

e An exception is signaled 


¢ You click on the Stop button in the main window 


For more information, choose Overview from the Help menu, then choose 
Starting and Resuming Execution (Go Command). 


1.5.8.2 Executing the Program by Step Unit 


Use the Step command to execute the program one or more step units ata 
time. 


By default, a step unit is one line of source code; and, by default, the 
debugger notifies you of the completion of a Step command by displaying a 
"stepped to..." message and the source line where execution is suspended. 


To execute one step unit, click on the Step button in the main window. 


You can use the pop-up menu for some common step options (for example, 
step into routine, step by instruction). 


To execute these and other step options, or to change the step unit or 
any Step command default, choose Step... from the Control menu. 
For example, you can make the default step unit signify "execute one 
instruction". 


For more information, choose Overview from the Help menu, then choose 
Executing the Program by Step Unit (Step Command). 


1.5.8.3 Suspending and Tracing Execution with Breakpoints and Tracepoints 


A breakpoint is a location in your program at which execution is to be 
suspended. Typical locations are routine declarations, program labels, and 
specific lines of source code. At a breakpoint, you can step into a routine, 
check the current value of a variable, and so on. | | 
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In addition to specifying unique locations, you can set breakpoints on every 
source line or on certain classes of VAX assembly-language instructions. 
You can also set breakpoints on certain kinds of events, such as exceptions 
and Ada tasking events. And you can set conditional breakpoints that 
trigger only when a specified expression is evaluated to be true. 


A tracepoint is like a breakpoint, except that execution continues after the 
debugger reports that the tracepoint has been reached. Tracepoints enable 
you to monitor the path of execution of your program through specified 
locations (for example, through routine calls). As with breakpoints, 

you can trace through classes of instructions, monitor events, and set 
conditional tracepoints. 


In general, to set, identify, or cancel breakpoints or tracepoints, choose 
Break... from the Control menu 


For more information, choose Overview from the Help menu, then choose 
Using Breakpoints and Tracepoints. 


1.5.8.4 Monitoring Changes in Variables with Watchpoints 
A watchpoint is a memory address, register, or (typically) a variable 
declared in the program whose value is monitored during program 
execution. If the value changes, the debugger suspends execution and 
reports the old and new values. 


Note that you can set a watchpoint on a nonstatic (stack or register) 
variable only when program execution is currently suspended within the 
scope of its defining routine—that is, when the defining routine is active 
on the call stack. 


To set, identify, or cancel watchpoints, choose Watch... from the Control 
menu. As with breakpoints and tracepoints, you have several options for 
setting watchpoints. 


For more information, choose Overview from the Help menu, then choose 
Using Watchpoints. 


1.5.9 Examining and Manipulating Program Data 


The debugger enables you to manipulate variables declared in your 
program, code locations (locations containing VAX instructions), memory 
addresses, registers, and language expressions. 


1.5.9.1 Operations with Variables 
To manipulate variables in your program, choose Variables from the Data 
menu. The Variables submenu provides the following operations: 


e Choose Examine Variable... to display the value of a variable. 
¢ Choose Deposit into Variable... to assign a value to a variable. 


e Choose Show Variable... to display information about a variable, such 
as its type, memory address or register, and path name. 
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Note that you can examine a nonstatic (stack or register) variable only 
when program execution is currently suspended within the scope of its 
defining routine—that is, when the defining routine is active on the call 
stack. | 


For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data, then choose Operations with 
Variables. 


1.5.9.2 Operations with Code Locations 


To manipulate code locations in your program (locations with VAX 
assembly-language instructions) choose Code from the Data menu. The 
Code submenu provides the following operations: 


¢ Choose Examine Code... to display the following: 


— The source line for a code location (for example, for a routine 
declaration). 


— The VAX instructions at a code location (for example, the 
instruction at the current PC value, where execution is suspended). 
The program counter (PC) is a VAX register that contains the 
address of the instruction to be executed next. 


¢ Choose Deposit Code... to deposit a VAX instruction at a memory 
address or into a register. 


e Choose Show Address... to display the memory address of a routine, 
line number, or other code location. 


For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data, then choose Operations with 
Code Locations. 


See also Section 1.3.2.4 and Section 1.5.6 for information about displaying 
instructions associated with your program. 


1.5.9.3 Operations with Addresses or Registers 


To manipulate memory addresses or registers, choose Addresses or 
Registers from the Data menu. The Addresses or Registers submenu 
provides the following operations: 


¢ Choose Examine Address or Register... to display the value stored at 
an address or in a register. 


¢ Choose Deposit into Address or Register... to change the value stored 
at an address or in a register. 


¢ Choose Symbolize Address or Register... to display the symbol (if any) 
that is associated with an address or register. 


For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data, then choose Operations with 
Addresses or Registers. 


Introduction to the Debugger: DECwindows Interface 
1.5 Using the Debugger 


1.5.9.4 Evaluating Language Expressions 
To evaluate a language expression, choose Language Expressions... from 
the Data menu. 


The debugger recognizes the operators and expression syntax of the 
currently set language. For example, if your program has an integer 
variable named WIDTH, you can use the Language Expressions dialog 
box to evaluate the expression WIDTH + 7. The debugger adds 7 to the 
current value of WIDTH and displays the result. 


For more information, choose Overview from the Help menu, then choose 
Specifying and Evaluating Language Expressions. See also Section 1.5.13 
for information about debugging multilanguage programs. 


1.5.10 Controlling Access to Symbols in Your Program 


To have full access to the symbols that are associated with your program 
(variable names, routine names, source code, line numbers, and so on), you 
must compile and link the program using the /DEBUG command qualifier, 
as explained in Section 1.2.1. 


Under these conditions, the way in which the debugger handles these 
symbols is transparent to you, in most cases. However, the following two 
areas might require action: 


e Setting and canceling modules 


e Resolving symbol ambiguities 


These two subjects are discussed in the next sections. For more 
information, choose Overview from the Help menu, then choose Controlling 
Access to Symbols in Your Program. 


1.5.10.1 Setting and Canceling Modules 
To facilitate symbol searches, the debugger loads symbol information 
from the executable image into a run-time symbol table (RST), where 
that information can be accessed efficiently. Unless symbol information 
is in the RST, the debugger does not recognize or properly interpret the 
associated symbols. 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of 
program execution. The loading process is called module setting, because 
all symbol information for a given module is loaded into the RST at one 
time. 


At dehugger startup, only the module containing the image transfer 
address is set. Subsequently, whenever execution of the program is 
interrupted, the debugger sets the module that contains the routine in 
which execution is suspended. This enables you to reference the symbols 
that should be visible at that location. 


If you try to reference a symbol in a module that has not been set, the 
debugger warns you that the symbol is not in the RST. For example: 


*DEBUG-W-NOSYMBOL, symbol ’X’ is not in symbol table 
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You must then set the module containing that symbol explicitly. To set a 
module, choose Modules... from the Data menu. The Modules dialog box 
lists the modules of your program and identifies which modules are set. 


For more information, choose Overview from the Help menu, then choose 
Controlling Access to Symbols in Your Program, then choose Setting and 
Canceling Modules. 


1.5.10.2 Resolving Symbol Ambiguities 
Symbol ambiguities can occur when a symbol (for example, a variable 
name X) is defined in more than one routine or other program unit. 


In most cases, the debugger resolves symbol ambiguities automatically. 
First it uses the scope and visibility rules of the currently set language. In 
addition, because the debugger permits you to specify symbols in arbitrary 
modules (to set breakpoints and so on), the debugger uses the ordering of 
routine calls on the call stack to resolve symbol ambiguities. 


In some cases, however, the debugger might respond as follows when you 
specify a symbol that is defined multiple times: 


e It might issue a "symbol not unique" message because it is not able to 
determine the particular declaration of the symbol that you intended. 


e It might reference a symbol declaration other than the one you want. 


To resolve such problems, you must specify a scope where the debugger 
should search for the particular declaration of the symbol. There are two 
techniques: 


¢ Specify a path name prefix with the symbol. For example, if the 
variable X is defined in two modules named COUNTER and SWAP, 
the path name SWAP\X uniquely specifies the declaration of X in 
module SWAP. This technique can always be used to resolve symbol 
ambiguities. 


¢ Ifthe different declarations of the symbol are within routines that are 
currently active on the call stack, use the Call Frame arrow buttons in 
the main window to reset the reference for looking up symbols to the 
appropriate call frame. With this technique you do not need to specify 
a path name prefix. 


For more information, choose Overview from the Help menu, then choose 
Controlling Access to Symbols in Your Program, then choose Resolving 
Symbol Ambiguities. 


1.5.11. Using the Debugger’s Command Interface 


The debugger is available in a command interface that runs on terminals 
and workstations (see Part II of this manual). When using that interface, 
you interact with the debugger by entering commands at the debugger 
prompt (DBG>). 
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When using the debugger’s DECwindows interface, you can open the 
COMMAND box, which enables you to enter debugger commands at the 
DBG> prompt: 


e To open the COMMAND box for just one command, press the DO key. 


¢ To open the COMMAND box indefinitely, choose Show Command... 
from the Customize menu. Choosing Hide Command from that menu 
closes the COMMAND box. 


You can also enter debugger commands in debugger command procedures 
and initialization files for execution under the DECwindows environment 
(see Section 1.5.12). 


For more information, choose Overview from the Help menu, then choose 
The Debugger’s Command Interface. 


1.5.12 Using Log Files, Initialization Files, Command Procedures 


When you use the debugger’s DECwindows interface, each of your actions 
results in one or more debugger commands. These commands are echoed 
in the COMMAND box by default. 


You can record in a log file the debugger commands that you enter directly 
or indirectly during a debugging session and the debugger’s responses to 
those commands. You can use log files to keep a record of your debugging 
sessions, or you can use them as command procedures in subsequent 
sessions. For more information, choose Overview from the Help menu, 
then choose Logging a Debugging Session into a File. 


You can create an initialization file containing debugger commands to 
set your default debugging modes, debugger window characteristics, 
and so on. When you invoke the debugger, those commands are 
executed automatically to tailor your debugging environment. For more 
information, choose Overview from the Help menu, then choose Using a 
Debugger Initialization File. 


You can direct the debugger to execute a command procedure (a file 
containing a sequence of debugger commands) to recreate a debugging 
session, to continue a previous session, or to avoid typing the same 
debugger commands many times during a debugging session. You can 
pass parameters to command procedures. For more information, choose 
Overview from the Help menu, then choose Using Debugger Command 
Procedures. 


1.5.13 Debugging Multilanguage Programs 


Within the same debugging session, you can debug modules whose source 
code is written in different languages. 


By default, the debugger language remains set to the language of the main 
program throughout the debugging session, even if execution is suspended 
within a module written in another language. To take full advantage of 
symbolic debugging with such modules, you can set the debugging context 
to another language by choosing Language from the Customize menu. 
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For more information, choose Overview from the Help menu, then choose 
Debugging Multilanguage Programs and Debugger Support for Languages. 


When debugging in any language, be sure also to consult the 
documentation supplied with that language. 


1.5.14 Debugging Shareable Images and Ada Tasking Programs 


The Data menu gives you access to operations related to debugging 
shareable images and VAX Ada tasking programs. 


By setting your debugging context to a shareable image that is linked with 
your program, you have access to the symbols declared in that image. By 
default, the main (executable) image is your debugging context. Choose 
Images... from the Data menu to set your debugging context to another 
image. For more information, choose Overview from the Help menu, then 
choose Debugging Shareable Images. 


When using the debugger with a VAX Ada tasking program, you can 
control the execution of individual tasks and display information about one 
or more tasks or the entire tasking system. Choose Tasks... from the Data 
menu to manipulate tasks. See also the VAX Ada documentation. 


1.5.15 Debugging Multiprocess Programs 


To debug a multiprocess program (a program that runs in more than one 
process), you must establish a multiprocess debugging configuration before 
invoking the debugger. That configuration enables you to interact with 
several processes from one debugging session. 


Enter the following command to establish a multiprocess debugging 
configuration: 


§$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 


After you have invoked the debugger, you can control the execution of 
individual processes, examine data associated with specific processes, 
display information in process-specific windows, and so on. 


Choose Processes... from the Data menu to manipulate processes. For 
more information, choose Overview from the Help menu, then choose 
Debugging Multiprocess Programs. 


1.5.16 Debugging Vectorized Programs 
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When using the debugger with a vectorized program (a program that uses 
VAX vector instructions) you can perform tasks such as the following: 


¢ Control and monitor the execution of vector instructions with 
breakpoints, watchpoints, and so on 


¢ Examine and deposit into the vector control registers (VCR, VLR, and 
VMR) and the vector registers (V0 to V15) 


e Examine and deposit vector instructions and their operands 
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e Perform masked operations on vector registers to display only certain 
register elements or override the masking associated with a vector 
instruction 


¢ Control synchronization between the scalar and vector processors 


For more information, choose Overview from the Help menu, then choose 
Debugging Vectorized Programs. 


1.5.17 Using the Keypad to Enter Commands 


When you invoke the debugger, a few commonly used debugger command 
sequences are automatically assigned to the keys on the numeric keypad 
(to the right of the main keyboard). Thus, you can perform certain 
functions either by choosing an item from a menu or by pressing a keypad 
key. 


The predefined key functions are identified in Figure 1-15. 
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Figure 1-15 


7 


DISP SRC,INST,OUT 
DISP INST,REG,OUT 
DISP 2 SRC, 2 INST 


4 


SCROLLULEFT 
SCROLL/LEFT:255 
SCROLULEFT... 


1 


EXAMINE 
EXAM“(prev) 
DISP 3 SRC, 3 INST 


STEP 


Keypad Key Functions Predefined by the Debugger— 
DECwindows Interface 


PF2 


HELP DEFAULT 
HELP GOLD 
HELP BLUE 


SCROLL/UP 
SCROLL/TOP 
SCROLUUP... 


5 


EX/SOU .0\%PC 
SHOW CALLS 
SHOW CALLS 3 


2 


SCROLL/DOWN 
SCROLL/BOTTOM 
SCROLL/DOWN... 


STEP/INTO 
STEP/OVER 


PF3 


SET MODE SCREEN 
SET MODE NOSCR 
DISP/GENERATE 


DISPLAY next 
SET PROC next 
DISP 2 SRC 


6 


SCROLL/RIGHT 
SCROLL/RIGHT:255 
SCROLL/RIGHT... 


3 


SEL SCROLL next 
SEL OUTPUT next 
DISP 3 SRC 





DISP next at FS 


DISP SRC, OUT 


? 


GO 
SEL/SOURCE next 
SEL/INST next 


ZK-0957A-GE 


Most keypad keys have three predefined functions—DEFAULT, GOLD, 


and BLUE. 


e To enter a key’s DEFAULT function, press the key. 


¢ To enter its GOLD function, first press and release the PF1 (GOLD) 
key, and then press the key. 


e To obtain its BLUE function, first press and release the PF4 (BLUE) 
key, and then press the key. 


In Figure 1-15, the DEFAULT, GOLD, and BLUE functions are listed 
within each key’s outline, from top to bottom, respectively. For example: 


e Pressing keypad key 0 enters the STEP command (like clicking on the 
Step button in the main window). 


e Pressing key PF1 and then keypad key 0 enters the STEP/AINTO 
command (like choosing Step Into Routine from the pop-up menu). 
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e Pressing key PF4 and then keypad key 0 enters the STEP/OVER 
command (like choosing Step Over routine from the pop-up menu). 
You can redefine keypad-key functions. 


For more information, choose Overview from the Help menu, then choose 
Entering Debugger Commands from the Keypad. 


1.6 Additional ee for Invoking the Debugger 


Section 1.2 describes how to compile and link your program prior to 
debugging, establish the default debugging configuration for one-process 
programs, and invoke the debugger in the usual way from a DECterm 
window. 


The sections that follow describe other options for invoking the debugger: 
e Invoke the debugger from a FileView window 


e Interrupt a program that is executing freely and then invoke the 
debugger 


¢ Override the debugger’s default (DECwindows) interface to achieve the 
following: 


— Display the debugger’s DECwindows interface on another 
workstation 


— Display the debugger’s command interface in a DECterm window, 
along with any program input/output 


— Display the debugger’s command interface and program input 
/output in separate DECterm windows 


In all cases, before invoking the debugger, first compile and link the 
modules of your program and establish the appropriate debugging 
configuration as explained in Section 1.2.1, Section 1.2.2, and 
Section 1.5.15. 


Note: You cannot run a program under debugger control over a DECnet 
link. Both the image to be debugged and the debugger must reside 
on the same node. 


For more information, including details on compilation and linking options 
that affect debugging, choose Overview from the Help menu, then choose 
Options for Invoking the Debugger. 


1.6.1. Invoking the Debugger from a FileView Window 
To invoke the debugger from a FileView window, proceed as follows: 
1 Choose Run from the FileView Files menu. A dialog box is displayed. 
2 Specify the executable image file to be debugged. 
3 Choose the Debug option. 
4 Click on OK. 
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1.6.2 Invoking the Debugger with the DCL DEBUG Command 


You can invoke the debugger while your program is executing freely (for 
example, if you suspect that the program might be in an infinite loop or if 
you see erroneous output). 


To invoke the debugger in this manner, proceed as follows: 


1. Enter the DCL command RUN/NODEBUG to execute the program 
without debugger control. 


2 Press CTRL/Y to interrupt the executing program. Control then passes 
to the DCL command interpreter. 


3 Enter the DCL command DEBUG to activate the debugger. When the 
debugger comes up, it displays the main, source, and output windows, 
sets the language-dependent parameters to the language of the module 
where execution was interrupted, and executes any user-defined 
initialization file. 


For example: 


$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
$ LINK/DEBUG EIGHTQUEENS 
S$ RUN/NODEBUG EIGHTQUEENS 


Interrupt 
$ DEBUG 
[invokes debugger] 


To help you identify where execution was interrupted, look at the source 
window and choose Call Stack... from the Data menu to identify the 
sequence of routine calls on the call stack. 


1.6.3  Overriding the Debugger’s Default Interface 
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By default, if your workstation is running VMS DECwindows, 
the debugger comes up in the DECwindows interface on the 


workstation specified by the DECwindows application-wide logical name 
DECWS$DISPLAY. 


This section explains how to override the debugger’s default DECwindows 
interface to achieve the following: 


¢ Display the debugger’s DECwindows interface on another workstation 


e Display the debugger’s command interface in a DECterm window, 
along with any program input/output 


e Display the debugger’s command interface and program input/output 
in separate DECterm windows 


The logical name DBG$DECW$DISPLAY enables you to override the 
default interface of the debugger. Note that, in most cases, there is no 
need to define DBG$DECW$DISPLAY, because the default implies the 
desired action. ; 
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Section 1.6.3.4 provides more information about the logical names 
DBG$DECW$DISPLAY and DECW$DISPLAY. 


1.6.3.1 Displaying the Debugger’s DECwindows Interface on Another Workstation 
If you are debugging a DECwindows application that uses most of the 
screen, you might find it useful to run the program on one workstation 
and display the debugger’s DECwindows interface on another. To do so, 
proceed as follows: 


1 


Enter a logical definition with the following syntax in the DECterm 
window from which you plan to run the program: 


DEFINE/JOB DBG$DECWS$DISPLAY workstation_pathname 


where workstation_pathname is the path name for the workstation 
where the debugger’s DECwindows interface is to come up. See the 
description of the SET DISPLAY command in the VMS DCL Dictionary 
for the syntax of this path name. 


It is recommended that you use a job definition. If you use a process 
definition, it must not have the CONFINE attribute. 


Run the program from that DECterm window. The debugger’s 
DECwindows interface comes up on the workstation specified by 
DBG$DECW$DISPLAY. The application’s windowing interface comes 
up on the workstation display where it normally does. 


1.6.3.2 Displaying the Command Interface in a DECterm Window | 
To display the debugger’s command interface in a DECterm window, along 
with any program input/output, proceed as follows: 


1 


Enter the following definition in the DECterm window from which you 
plan to run the program: 


$ DEFINE/JOB DBGSDECWSDISPLAY " " 


You can specify one or more space characters between the quotation 
marks. It is recommended that you use a job definition for the logical 
name. If you use a process definition, it must not have the CONFINE 
attribute. 


Run the program from that DECterm window. The debugger’s 
command interface comes up in the same window. 


For example: 


$ 
$ 
$ 
$ 


DEFINE/JOB DBGSDECWSDISPLAY " " 
PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
LINK/DEBUG EIGHTQUEENS 

RUN EIGHTQUEENS 


VAX DEBUG Version 5.4 


S$DEBUG-I-INITIAL, language is PASCAL, module set to EIGHTQUEENS 
DBG> 


You can now enter debugger commands as described in Part II of this 
manual, which starts with Chapter 2. 
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1.6.3.3 Displaying the Command Interface and Program Input/Output in Separate 
DECterm Windows 


This section describes how to display the debugger’s command interface 
in a separate DECterm window from the DECterm window from which 
you invoke the debugger. This separate window is useful when using the 
command interface to debug a screen-oriented program: 


e The program’s input/output is displayed in the window from which you 
invoke the debugger. 


e The debugger’s input/output, including any screen-mode display, is 
displayed in the separate window. 


The effect is the same as entering the debugger command SET MODE 
SEPARATE at the DBG> prompt on a workstation running VWS rather 
than DECwindows. (The command SET MODE SEPARATE is not valid 
when used in a DECterm window.) 


The following example shows how to display the debugger’s command 
interface in a separate debugger window titled “Debugger”. 


1 Create the command procedure SEPARATE _WINDOW.COM shown in 
Example 1-1. 


2 Execute the command procedure: 


$ @SEPARATE WINDOW 
SDCL-I-ALLOC, _MYNODESTWA8: allocated 


A new DECterm window is created with the attributes specified in 
SEPARATE _WINDOW.COM. 


3 Follow the steps in Section 1.6.3.2 to display the debugger’s command 
interface. The interface is displayed in the new window. 


4 You can now enter debugger commands in the debugger window. 
Program input/output is displayed in the DECterm window from which 
you invoked the debugger. 


5 When you end the debugging session with the EXIT command, control 
returns to the DCL prompt in the program input/output window, but 
the debugger window remains open. 


6 To display the debugger’s command interface in the same window as 
the program’s input/output (as in Section 1.6.3.2), enter the following 
commands: 


S DEASSIGN/JOB DBGSINPUT 
S$ DEASSIGN/JOB DBGSOUTPUT 


The debugger window remains open until you close it explicitly. 
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Example 1-1 Command Procedure SEPARATE_WINDOW.COM 


S$ ! Simulates effect of SET MODE SEPARATE from a DECterm window 
S$ ! 
$ CREATE/TERMINAL/NOPROCESS - 

/WINDOW_ATTRIBUTES= (TITLE="Debugger", - 

ICON _NAME="Debugger", ROWS=40) - 

/ DEF INE LOGICAL= (TABLE=LNMSJOB, DBGSINPUT, DBGSOUTPUT) 
ALLOCATE DBGSOUTPUT 
EXIT 

! 

! The command CREATE/TERMINAL/NOPROCESS creates a DECterm 
window without a process. 


— 


The /WINDOW_ATTRIBUTES qualifier specifies the window’s 
title (Debugger), icon name (Debugger), and the number 
of rows in the window (40). 


DBGSINPUT and DBGSOUTPUT to the window, so that it becomes 
the debugger input and output device. 


The command ALLOCATE DBGSOUTPUT causes the separate window 
to remain open when you end the debugging session. 


GWA MAANMAUHONMONUMMUMMNNMMNNMN 


: 
: 
' 
! The /DEFINE LOGICAL qualifier assigns the logical names 
I 
: 
! 
: 
; 


1.6.3.4 Explanation of DBGSDECWS$DISPLAY and DECW$DISPLAY 
By default, if your workstation is running VMS DECwindows, 
the debugger comes up in the DECwindows interface on the 
workstation specified by the DECwindows application-wide logical name 
DECW$DISPLAY. DECW$DISPLAY is defined in the job table by FileView 
or DECterm. It points to the display device for the workstation. 


For information about DECW$DISPLAY, see the description of the 
DCL commands SET DISPLAY and SHOW DISPLAY in the VMS DCL 


Dictionary. 


The logical name DBG$DECW$DISPLAY is the debugger-specific 
equivalent of DECW$DISPLAY. DBG$DECW$DISPLAY is analogous 

to the debugger-specific logical names DBG$INPUT and DBG$OUTPUT. 
These enable you to reassign SYS$INPUT and SYS$OUTPUT, respectively, 
to specify the device on which debugger input and output are to appear. 


The default user interface of the debugger results when 
DBG$DECWS$DISPLAY is undefined or has the same translation as 
DECW$DISPLAY. By default, DBG$DECW$DISPLAY is undefined. 


The algorithm that the debugger follows when using the logical definitions 
of DECW$DISPLAY and DBG$DECW$DISPLAY is as follows: 


1 Ifthe logical name DBG$DECWS$DISPLAY is defined, then use it. 
Otherwise, use the logical name DECW$DISPLAY. 


2 ‘Translate the logical name. If its value is not null (if the string 
contains characters other than space characters), the DECwindows 
interface comes up on the specified workstation. If the value is null (if 
the string consists only of space characters), the command interface 
comes up in the DECterm window. 
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Sample Program EIGHTQUEENS 


Example 1-2 is the Pascal program, EIGHTQUEENS, that is used in 
Section 1.4. Line numbers correspond to the compiler assigned line 
numbers as displayed in a debugger source window. 


The program prints out the possible locations on a chess board at which 
each of eight queens can be positioned safely, without threatening each 
other. A queen can be threatened by another queen on the same row, in 
the same column, or along a diagonal. 


When executed, the program produces several lines of integers. For 
example: 


Cr a a ede er| 
re OO OVW OD 
W WN CO ~] W 
MriAN A ~] 
N~IA oN NY 
SOW WwW op 


NMP RB Pe 
IO WB OO 


m ®m GW W 
Fr @® ~) 
; Oey, 
oO Cc ~)] © 
WNNF on 
WwIn 
IWDNF 
NO nd om 


8.2 O98 Ai 7-4 6 
oes ae 9 MR as a 
84136275 


Each line of output represents a possible safe configuration of the eight 
queens on a standard 8-row by 8-column chess board. For example, the 
output line 41582736 indicates that queens can be positioned safely at 
rows 4, 1, 5, 8, 2, 7, 3, and 6 of columns 1 to 8, respectively. 


Example 1-2 Sample Program EIGHTQUEENS 


1: PROGRAM Eightqueens (OUTPUT) ; 

2 VAR 

3 I : INTEGER; 

4; A : ARRAY[1..8] OF BOOLEAN; 
53 B : ARRAY[2..16] OF BOOLEAN; 
6: C : ARRAY[-7..7] OF BOOLEAN; 
Ya X : ARRAY[1..8] OF INTEGER; 
Ss Safe : BOOLEAN; K: INTEGER; 
Os 

Os PROCEDURE Print; 
dO Ba BEGIN (* Print *) 
12: FOR K := 1 TO 8 DO 
LSs WRITE (X[K]: 2); 

14; WRITELN; 

dhe y- END; (* Print *) 


(continued on next page) 
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Example 1-2 (Cont.) Sample Program EIGHTQUEENS 





16: 

dla PROCEDURE Trycol(J : INTEGER) ; 
18: VAR 

19: I : INTEGER; 

20: 

213 PROCEDURE Setqueen; 
22% BEGIN (* Setqueen *) 
2% A[I] := FALSE; 

24: B({I+J] := FALSE; 
ZS C{I-J] := FALSE; 
ZO END; (* Setqueen *) 
243 

28: PROCEDURE Removequeen; 
2g BEGIN (* Removequeen *) 
30? A[I] := TRUE; 

SL: B[I+J] := TRUE; 
32% Cli= J] <= TRUES 
cer END; (* Removequeen *) 
34: 

55% BEGIN (* Trycol *) 

36% I := QO; 

Sy ae REPEAT 

38: L = aly 

39: Safe := A[I] AND B[It+tJ] AND C[I-J]; 
40: IF Safe THEN 

41: BEGIN 

42: Setqueen; 

43: X{J] := I; 

44; IF J < 8 THEN 
45: Trycol (J+1) 
46: ELSE 

47; Print; 

48: Removequeen; 
49: END; 

50: UNTIL I = 8; 

Sis END? .(* Trycol. *} 

52: 

53: BEGIN (* Eightqueens *) 
54% FOR I := 1 TO 8 DO 

553 A[I] := TRUE; 

56% FOR I := 2 TO 16 DO 

Bs B[I] := TRUE; 

aor FOR I := -7 TO 7 DO 

59% C{I] := TRUE; 

60: Trycol (1); 

61s WRITELN; 


62: END. (* Eightqueens *) 
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Partlil Using the Debugger: Command Interface 


This part contains complete information about the VMS debugger’s command 
interface. 


For information about the debugger’s DECwindows interface, see Part I. 


Ps Introduction to the Debugger: Command Interface 


This chapter introduces the VMS Debugger’s command interface. For 
information about the debugger’s DECwindows interface, see Chapter 1. 


The following information is provided in this chapter: 

e An overview of the debugger’s features (Section 2.1) 

e Enough information to get you started (Section 2.2) 

e Asample debugging session (Section 2.3) 

e A list of the debugger commands, by function (Section 2.4) 


After you have read this chapter, consult the rest of this manual for 
additional details about the command interface. 





2.1 Overview of the Debugger 


The debugger is a tool that helps you locate run-time programming or logic 
errors, also known as bugs. You use the debugger with a program that 
has been compiled and linked successfully but does not run correctly. For 
example, the program might give incorrect output, go into an infinite loop, 
or terminate prematurely. 


You locate errors with the debugger by observing and manipulating your 
program interactively as it executes. By entering debugger commands at 
the terminal, you can do the following tasks: 


e¢ Control the program’s execution—start the program, stop at points of 
interest, resume execution, and so on 


e Trace the execution path of the program 

e Monitor changes in variables and other program entities 

e Monitor exception conditions and language-specific events 

e Examine and modify the values of variables, or force events to occur 


e In some cases, test the effect of modifications without having to edit 
the source code, recompile, and relink 


These are the basic debugging techniques. After you are satisfied that 
you have found the error in the program, you can edit the source code and 
compile, link, and execute the corrected version. 


As you use the debugger and its documentation, you will discover 
variations on the basic techniques. You can also tailor the debugger 
for your own needs. The next section summarizes the debugger features. 
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2.1.1 Functional Features 
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Programming Language Support 


You can use the debugger with the following VAX languages: Ada, BASIC, 
BLISS, C, COBOL, DIBOL, FORTRAN, MACRO-32, Pascal, PL/I, RPG II, 
and SCAN. The debugger recognizes the syntax, data typing, operators, 
expressions, scoping rules, and other constructs of a given language. If 
your program is written in more than one language, you can change the 
debugging context from one language to another during a debugging 
session with the SET LANGUAGE command. 


Symbolic Debugging 


The VMS Debugger is a symbolic debugger. You can refer to program 
locations by the symbols you used for them in your program—the names of 
variables, routines, labels, and so on. You do not need to specify memory 
addresses or VAX registers when referring to program locations, although 
you can, if you want. 


Support for All Data Types 


The debugger understands all compiler generated data types, such as 
integer, floating point, enumeration, record, array, and so on. It displays 
the values of program variables according to their declared type. 


Flexible Data Format 


The debugger permits a variety of data forms and types for entry and 
display. By default, the source language of the program determines 

the format used for the entry and display of data. You can also impose 
other formats. For example, by using a type or radix qualifier with the 
EXAMINE command, you can display the contents of a program location 
in ASCII, word-integer, or floating-point format. 


Starting or Resuming Program Execution 


You start or resume program execution with the GO or STEP commands. 
The GO command causes the program to execute until a breakpoint 

is reached, a watchpoint is modified, an exception is signaled, or the 
program terminates. The STEP command enables you to execute a 
specified number of lines or instructions, or up to the next instruction 
of a specified class. 


Breakpoints 


By setting breakpoints with the SET BREAK command, you can suspend 
program execution at specified locations and check the current status 

of your program. Rather than specify a location, you can also suspend 
execution on certain classes of instructions or on every source line. Also 
you can suspend execution on certain kinds of events, such as exceptions 
and Ada tasking events. 
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Tracepoints 


By setting tracepoints with the SET TRACE command, you can monitor 
the path of program execution through specified locations. When a 
tracepoint is triggered, the debugger reports that the tracepoint was 
reached and then continues execution. As with the SET BREAK command, 
you can also trace through classes of instructions and monitor events. 


Watchpoints 


By setting a watchpoint with the SET WATCH command, you can cause 

execution to stop whenever a particular variable or other memory location 
has been modified. When a watchpoint is triggered, the debugger suspends 
execution at that point and reports the old and new values of the variable. 


Manipulation of Variables and Program Locations 


With the EXAMINE command, you can determine the value of a variable 
or program location. The DEPOSIT command enables you to change that 
value. You can then continue execution to see the effect of the change, 
without having to recompile, relink, and rerun the program. 


Evaluation of Expressions 


With the EVALUATE command, you can compute the value of a source- 
language expression or an address expression. You specify expressions and 
operators in the syntax of the language to which the debugger is currently 
set. | 


Control Structures 


You can use logical control structures (FOR, IF, REPEAT, WHILE) in 
commands to control the execution of other commands. 


Shareable Image Debugging 


You can debug shareable images (images that are not directly executable). 
The SET IMAGE command enables you to reference the symbols declared 
in a shareable image. 


Multiprocess Debugging 


You can debug multiprocess programs (programs that run in more than 
one VMS process). The commands SHOW PROCESS and SET PROCESS 
enable you to display process information and control the execution of 
images in individual processes. 


Vector Debugging 


You can debug vectorized programs (programs that use VAX vector 
instructions). You can control and monitor execution at the vector 
instruction level, examine and deposit vector instructions, manipulate the 
contents of vector registers, use a mask to display specific vector elements, 
and control synchronization between the scalar and vector processors. 
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Terminal and Workstation Support 


The debugger supports all VT-series terminals and MicroVAX 
workstations. 


2.1.2 Convenience Features 
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Online Help 


Online help is always available during a debugging session. Online help 
contains information about all debugger commands and selected topics. 


Source Code Display 


You can display lines of source code for all supported languages during a 
debugging session. 


Screen Mode 


In screen mode, you can display and capture various kinds of information 
in scrollable windows that can be moved around the screen and resized. 
Automatically updated source, instruction, and register displays are 
available. You can selectively direct debugger input, output, and diagnostic 
messages to displays. You can also create "DO" displays that capture the 
output of specific command sequences. 


Keypad Mode 


When you invoke the debugger, several commonly used debugger command 
sequences are assigned by default to the keys of the numeric keypad (if 
you have a VT52, VT100, or LK201 keyboard). Thus, you can enter these 
commands with fewer keystrokes than if you were to type them at the 
keyboard. You can also create your own key definitions. 


Source Editing 


As you find errors during a debugging session, you can use the EDIT 
command to invoke any editor available on your system. You specify the 
editor you wish with the SET EDITOR command. If you use the VAX 
Language-Sensitive Editor, the editing cursor is automatically positioned 
within the source file whose code appears in the screen-mode source 
display. 


Command Procedures 


You can direct the debugger to execute a command procedure (a file 

of debugger commands) to recreate a debugging session, to continue a 
previous session, or to avoid typing the same debugger commands many 
times during a debugging session. You can pass parameters to command 
procedures. 
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Initialization Files 


You can create an initialization file containing commands to set your 
default debugging modes, screen display definitions, keypad key 
definitions, symbol definitions, and so on. When you invoke the debugger, 
those commands are executed automatically to tailor your debugging 
environment. 

Log Files 


You can record in a log file the commands you enter during a debugging 
session and the debugger’s responses to those commands. You can use 
log files to keep track of your debugging efforts, or you can use them as 
command procedures in subsequent debugging sessions. 

Symbol Definitions 


You can define your own symbols to represent lengthy commands, address 
expressions, or values in abbreviated form. 


2.2 Getting Started with the Debugger 


The way you use the debugger depends on several factors: the kind of 
program you are working on, the kinds of errors you are looking for, and 
your own personal style and experience with the debugger. This section 
explains the following basic functions that apply to most situations. 


¢ Compiling and linking your program to prepare for debugging 

e Establishing the debugging configuration 

e Invoking the debugger 

e Ending a debugging session 

e Interrupting program execution and aborting debugger commands 

¢ Entering debugger commands and getting online help 

e Viewing your source code with the TYPE command and in screen mode 


¢ Controlling program execution with the GO, STEP, and SET BREAK 
commands, and monitoring execution with the SHOW CALLS, SET 
TRACE, and SET WATCH commands 


e Examining and manipulating data with the EXAMINE, DEPOSIT, and 
EVALUATE commands 


¢ Controlling symbol references with path names and the SET MODULE 
and SET SCOPE commands 
Several examples are language specific. However, the general concepts are 


readily adaptable to all supported languages. 


The sample debugging session in Section 2.3 illustrates how to use some of 
this information to locate an error and correct it. 
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Note: 


Compiling and Linking a Program to Prepare for Debugging 


Before you can use the debugger, you must compile and link the modules 
(compilation units) of your program as explained in this section. The 
following example shows how to compile and link a FORTRAN program, 
consisting of a single compilation unit named FORMS, before using the 
debugger. 


The /DEBUG and /NOOPTIMIZE qualifiers are compiler command 
defaults for some languages. These qualifiers are used in the 
example for emphasis. 


$ FORTRAN/DEBUG/NOOPTIMIZE FORMS 
$ LINK/DEBUG FORMS 


The /DEBUG qualifier on the compiler command (FORTRAN in this case) 
directs the compiler to write the symbol information associated with 
FORMS into the object module, FORMS.OBJ, in addition to the code and 
data for the program. This symbol information enables you to use the 
names of variables and other symbols declared in FORMS in debugger 
commands. If your program has several compilation units, you must 
compile each unit whose symbols you want to reference with the /DEBUG 
qualifier. 


Some compilers optimize the object code to reduce the size of the program 
or to make it run faster. In such cases you should compile your program 
with the /NOOPTIMIZE command qualifier (or equivalent). Otherwise, the 
contents of some program locations might be inconsistent with what you 
would expect from viewing the source code. 


The /DEBUG qualifier on the LINK command causes the linker to include 
all symbol information that is contained in FORMS.OBJ in the executable 
image. The qualifier also causes the VMS image activator to start the 
debugger at run time. If your program has several object modules, you 
need to specify those modules in the LINK command, for most languages. 


Establishing the Debugging Configuration 


Before invoking the debugger as explained in Section 2.2.3, check that the 
debugging configuration is appropriate for the kind of program you are 
going to debug. 


You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or 
several processes, respectively. The configuration depends on the current 
definition of the logical name DBG$PROCESS. Thus, before invoking the 
debugger, enter the DCL command SHOW LOGICAL DBG$PROCESS to 
determine the definition of DBG$PROCESS. 


Most of this chapter covers programs that run in only one process. For 
such programs, DBG$PROCESS either should be undefined, as in the 
following example, or should have the value DEFAULT: 


S$ SHOW LOGICAL DBGSPROCESS 
SSHOW-S-NOTRAN, no translation for logical name DBGSPROCESS 
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If DBG$PROCESS has the value MULTIPROCESS, and you want to 
debug a program that runs in only one process, enter the following 
command: 


$ DEFINE DBGSPROCESS DEFAULT 


For more information about multiprocess debugging, see Chapter 10. 


2.2.3 Invoking the Debugger 


After you compile and link your program and establish the appropriate 
debugging configuration, you can then invoke the debugger. To do so, 
enter the DCL command RUN, specifying the executable image of your 
program as the parameter. The following example shows how the debugger 
identifies itself after you invoke it: 


$ RUN FORMS 
VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is FORTRAN, module set to FORMS 
DBG> 


The diagnostic message that is displayed at debugger startup indicates 
that this debugging session is initialized for a FORTRAN program and 
that the name of the main program unit (the module containing the image 
transfer address) is FORMS. The initialization sets up language-dependent 
debugger parameters. 


At this point, execution is suspended at the beginning of the main 
program. The DBG> prompt, which is displayed whenever the debugger 
suspends execution, indicates that you can now enter debugger commands, 
as explained in Section 2.2.6. 


2.2.4 Ending a Debugging Session 


To end a debugging session and return to DCL level, type EXIT or press 
CTRL/Z: 


DBG> EXIT 
$ 


The following message, displayed during a debugging session, indicates 
that your program has completed normally: 


SDEBUG-I--EXITSTATUS, is ’SSYSTEM-S-NORMAL, normal successful completion’ 
DBG> 


If you want to continue debugging after seeing this message, type EXIT 
and start a new debugging session with the DCL RUN command. You 
could also restart execution from within the debugging session with a 
command such as GO %LINE 1. However, this can produce unexpected 
results if, for example, some variables have different values from when 
you first ran the program. 
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2.2.5 Interrupting Program Execution and Aborting Debugger Commands 


If your program goes into an infinite loop during a debugging session 
so that the debugger prompt does not reappear, press CTRL/C. This 
interrupts program execution and returns you to the debugger prompt 
(pressing CTRL/C does not end the debugging session). For example: 


DBG> GO 


DBG> 


You can also press CTRL/C to abort the execution of a debugger command. 
This is useful if a command takes a long time to complete. 


Pressing CTRL/C when the program is not running or when the debugger 
is not performing an operation has no effect. 


If your program already has a CTRL/C AST service routine enabled, use 
the SET ABORT_KEY command to assign the debugger’s abort function to 
another CTRL—key sequence. 


Pressing CTRL/Y from within a debugging session has the same effect as 
pressing CTRL/Y during the execution of a program. Control is returned 
to the DCL command interpreter ($ prompt). 


2.2.6 Entering Debugger Commands 
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You can enter debugger commands any time you see the debugger prompt 
(DBG>). To enter a command, type it at the keyboard and press RETURN. 
See Section 1 of the command dictionary for complete rules on entering 
debugger commands. 


To obtain online help about debugger commands and specific subjects, 
proceed as follows: 


¢ To list the help topics, enter the command HELP. 

¢ For an explanation of the help system, enter the command HELP 
HELP. 

For example: 


e To display help about the STEP command, enter the command HELP 
STEP. 


¢ To display help about debugger diagnostic messages, enter the 
command HELP MESSAGES. 


Section 2 of the command dictionary explains the general format and 
severity levels of debugger diagnostic messages. To obtain online help 
about a debugger message, use the following general command format: 


HELP MESSAGES message-identifier 
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For example, to display information about the message whose identifier is 
NOSYMBOL, enter the following command: 


DBG> HELP MESSAGES NOSYMBOL 
When you invoke the debugger, a few commonly used command sequences 
are automatically assigned to the keys on the numeric keypad (to the right 


of the main keyboard). Thus, you can perform certain functions either by 
typing a command or by pressing a keypad key. 


The predefined key functions are identified in Figure 2-1. 


Most keypad keys have three predefined functions—DEFAULT, GOLD, 
and BLUE. 


¢ To enter a key’s DEFAULT function, press the key. 


¢ To enter its GOLD function, first press and release the PF1 (GOLD) 
key, and then press the key. 


e To enter its BLUE function, first press and release the PF4 (BLUE) 
key, and then press the key. 


In Figure 2-1, the DEFAULT, GOLD, and BLUE functions are listed 
within each key’s outline, from top to bottom, respectively. For example: 


e Pressing keypad key 0 enters the STEP command. 
e Pressing key PF1 and then key 0 enters the STEP/INTO command. 
e Pressing key PF'4 and then key 0 enters the STEP/OVER command. 


Normally, keys 2, 4, 6, and 8 scroll screen displays down, left, right, 

or up, respectively. By putting the keypad in the MOVE, EXPAND, or 
CONTRACT state, indicated in Figure 2-1, you can also use these keys to 
move, expand, or contract displays in four directions. Enter the command 
HELP KEYPAD to display the keypad key definitions. 


You can redefine keypad key functions with the DEFINE/KEY command. 


2.2./ Displaying Source Code 


The debugger provides two modes for displaying information: noscreen 
mode and screen mode. By default, when you invoke the debugger, you are 
in noscreen mode, but you might find that it is easier to view source code 
in screen mode. The following sections briefly describe both modes. 


2.2.7.1 Noscreen Mode 
Noscreen mode is the default, line-oriented mode of displaying input 
and output. The interactive examples throughout this chapter, excluding 
Section 2.2.7.2, illustrate noscreen mode. 
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Figure 2-1 Keypad Key Functions Predefined by the Debugger—Command Interface 
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DISP 3 SRC, 3INST | SCROLL/DOWN... | DISP 3 SRC 

ENTER 


STEP 
STEP/INTO 
STEP/OVER 


LK201 Keyboard: 


Press Keys 2,4,6,8 
Fi7 SCROLL 
F18 MOVE 

Fi9 EXPAND 
F20 CONTRACT 

VT-100 Keyboard: 

Type Keys 2,4,6,8 
SET KEY/STATE=DEFAULT SCROLL 
SET KEY/STATE=MOVE MOVE 

SET KEY/STATE=EXPAND EXPAND 
SET KEY/STATE=CONTRACT CONTRACT 
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MOVE/UP 
MOVE/UP:999 
MOVE/UP:5 


“MOVE" 




















MOVE/RIGHT 
MOVE/RIGHT:999 
MOVE/RIGHT:10 


MOVE/LEFT 
MOVE/LEFT:999 
MOVE/LEFT:10 









MOVE/DOWN 
MOVE/DOWN:999 
MOVE/DOWN:5 











EXPAND/UP 
EXPAND/UP:999 
EXPAND/UP:5 


"EXPAND" 



















EXPAND/RIGHT 
EXPAND/RIGHT:999 
EXPAND/RIGHT:10 


EXPAND/LEFT 
EXPAND/LEFT :999 
EXPAND/LEFT:10 






EXPAND/DOWN 
EXPAND/DOWN:999 
EXPAND/DOWN:5 








EXPAND/UP:-1 
EXPAND/UP:~999 
EXPAND/UP:-5 





“CONTRACT” 



















EXPAND/RIGHT:—1 
EXPAND/RIGHT:-999 
EXPAND/RIGHT:-10 


EXPAND/LEFT:~1 
EXPAND/LEFT:-999 
EXPAND/LEFT:-10 






EXPAND/DOWN:~1 
EXPAND/DOWN:-999 
EXPAND/DOWN:-5 
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In noscreen mode, use the TYPE command to display one or more source 
lines. For example, the following command displays line 7 of the module 
in which execution is currently suspended: 


DBG> TYPE 7 
module SWAP ROUTINES 

fi TEMP := A; 
DBG> 


The display of source lines is independent of program execution. To 
display source code from a module other than the one in which execution 
is currently suspended, use the TYPE command with a path name to 
specify the module. For example, the following command displays lines 16 
to 21 of module TEST: 


DBG> TYPE TEST\16:21 


Path names are discussed in more detail in Section 2.2.8.1, in conjunction 
with the STEP command. 


You can also use the EXAMINE/SOURCE command to display the source 
line for a routine or any other program location that is associated with an 
instruction. 


Note that the debugger also displays source lines automatically when 
it suspends execution at a breakpoint or watchpoint or after a STEP 
command, or when a tracepoint is triggered (see Section 2.2.8). 


After displaying source lines at various locations in your program, you 
can redisplay the location at which execution is currently suspended by 
pressing keypad key 5. 


If the debugger cannot locate source lines for display, it issues a diagnostic 
message. Source lines might not be available for a variety of reasons. For 
example: 


e Execution is suspended within a module that was compiled or linked 
without the /DEBUG command qualifier. 


e Execution is suspended within a system or shareable image routine for 
which no source code is available. 


e The source file was moved to a different directory after it was compiled 
(the location of source files is embedded in the object modules). In this 
case, use the SET SOURCE command to specify the new location. 


e The module might need to be "set" with the SET MODULE command. 
Module setting is explained in Section 2.2.10.1. 


To invoke noscreen mode from screen mode, press the keypad key sequence 
GOLD-PF3 (or type SET MODE NOSCREEN). Note that you can use the 
TYPE and EXAMINE/SOURCE commands in screen mode as well as 
noscreen mode. 
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2.2.7.2 Screen Mode 
Screen mode provides the easiest way to view your source code. To invoke 
screen mode, press keypad key PF3 (or type SET MODE SCREEN). In 
screen mode, by default the debugger splits the screen into three displays 
named SRC, OUT, and PROMPT, as illustrated in Figure 2-2. 


Figure 2-2 Default Screen Mode Display Configuration 












SRC: module SWAP_ROUTINES— scroll-source 


2: with Text IO; use TEXT I0; 
3: package body SWAP ROUTINES is 


4 procedure SWAPT (A,B: in out INTEGER) is 
5? TEMP: INTEGER; 
G: begin 
ae TEMP := A; 
—> 8 A := B; 
9: B := TEMP; 
10: end; 









procedure SWAP2 (A,B: 
— OUT-output 

stepped to SWAP ROUTINES\SWAP1\%LINE 8 
SWAP _ROUTINES\SWAP1\A: 35 


in out COLOR) is 








— PROMPT™ error-program-prompt 
DBG> STEP 
DBG> EXAMINE A 


DBG> 
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The SRC display shows the source code of the module in which execution is 
currently suspended. An arrow in the left column points to the source line 
corresponding to the current value of the program counter (PC). The PC 
is a VAX register that contains the memory address of the instruction to 
be executed next. The line numbers, which are assigned by the compiler, 
match those in a listing file. As you execute the program, the arrow moves 
down and the source code is scrolled vertically to center the arrow in the 
display. 


The OUT display captures the debugger’s output in response to the 
commands that you enter. The PROMPT display shows the debugger 
prompt, your input (the commands that you enter), debugger diagnostic 
messages, and program output. 


Both SRC and OUT are scrollable so you can see whatever information 
might scroll beyond the display window’s edge. Use keypad key 3 to select 
the display to be scrolled (by default, SRC is scrolled). Use keypad key 8 
to scroll up and keypad key 2 to scroll down. Scrolling a display does not 
affect program execution. 
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In screen mode, if the debugger cannot locate source lines for the routine 
in which execution is currently suspended, it tries to display source lines 
in the next routine down on the call stack for which source lines are 
available. If the debugger can display source lines for such a routine, it 
issues the following message: 


SDEBUG-I-SOURCESCOPE, Source lines not available for .0\$%PC. 
Displaying source in a caller of the current routine. 


In such cases, the arrow in the SRC display identifies the line that 
contains code following the call statement in the calling routine. 


2.2.8 Controlling and Monitoring Program Execution 
This section explains how to perform the following tasks: 
e Start and resume program execution 


¢ Execute the program to the next source line, instruction, or other step 
unit 


¢ Determine where execution is currently suspended 
¢ Use breakpoints to suspend program execution at points of interest 


e Use tracepoints to trace the execution path of your program through 
specified locations 


¢ Use watchpoints to monitor changes in the values of variables 


With this information you can pick program locations where you can then 
test and manipulate the contents of variables as described in Section 2.2.9. 


2.2.8.1 Starting or Resuming Program Execution 
Use the GO command to start or resume program execution. 


After it is started with the GO command, program execution continues 
until one of the following events occurs: 


e The program completes execution 

¢ A breakpoint is reached 

e A watchpoint is activated 

e An exception is signaled 

¢ You press CTRL/C 

With most programming languages, when you invoke the debugger, 
execution is initially suspended directly at the beginning of the main 


program. Entering a GO command at this point quickly enables you to 
test for an infinite loop or an exception. 


If an infinite loop occurs during execution, the program does not terminate, 
so the debugger prompt does not reappear. To obtain the prompt, interrupt 
execution by pressing CTRL/C (see Section 2.2.5). If you are using screen 
mode, the pointer in the source display indicates where execution stopped. 
You can also use the SHOW CALLS command to identify the currently 
active routine calls on the call stack (see Section 2.2.8.3). 
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If an exception that is not handled by your program is signaled, the 
debugger interrupts execution at that point so that you can enter 
commands. You can then look at the source display and a SHOW CALLS 
display to find where execution is suspended. 


The most common use of the GO command is in conjunction with 
breakpoints, tracepoints, and watchpoints, as described in Section 2.2.8.4, 
Section 2.2.8.5, and Section 2.2.8.6, respectively. If you set a breakpoint 
in the path of execution and then enter the GO command, execution is 
suspended at that breakpoint. Similarly, if you set a tracepoint, execution 
is monitored through that tracepoint. And if you set a watchpoint, 
execution is suspended when the value of the "watched" variable changes. 





2.2.8.2 Executing the Program by Step Unit 


Use the STEP command to execute the program one or more step units at 
a time. 


By default, a step unit is one line of source code. In the following example, 
the STEP command executes one line, reports the action ("stepped 

to... "), and displays the line number (27) and source code of the line 

to be executed next: 


DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
aad X := X + 1; 

DBG> 


Execution is now suspended at the first machine code instruction for line 
27 of module TEST. Line 27 is in COUNT, a routine within module TEST. 


When displaying a program symbol (for example, a line number, 
routine name, or variable name), the debugger always uses a path 
name. A path name consists of the symbol plus a prefix that identifies 
the symbol’s location. In the preceding example, the path name is 
TEST\ COUNT\ @LINE 27. The leftmost element of a path name is 
the module name. Moving toward the right, the path name lists any 
successively nested routines and blocks that enclose the symbol. A 
backslash character (\ ) is used to separate elements (except when the 
language is Ada, where a period is used, to parallel Ada syntax). 


A path name uniquely identifies a symbol of your program to the debugger. 
In general, you need to use path names in commands only if the debugger 
cannot resolve a symbol ambiguity in your program (see Section 2.2.10). 

Usually the debugger can determine the symbol you mean from its context. 


When using the STEP command, note that only those source lines for 
which code instructions were generated by the compiler are recognized 
as executable lines by the debugger. The debugger skips over any other 
lines—for example, comment lines. 


You can specify different stepping modes, such as stepping by instruction 
rather than by line (SET STEP INSTRUCTION). Also, by default, the 
debugger steps "over" called routines—execution is not suspended within 
a called routine, although the routine is executed. By entering the SET 
STEP INTO command, you direct the debugger to suspend execution 
within called routines as well as within the routine in which execution is 
currently suspended (SET STEP OVER is the default mode). 
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2.2.8.3 Determining Where Execution ls Suspended 
The SHOW CALLS command is useful when you are unsure where 
execution is suspended during a debugging session (for example, after 
a CTRL/C interruption). 


The command displays a traceback that lists the sequence of calls 
leading to the routine in which execution is suspended. For each routine 
(beginning with the one in which execution is suspended), the debugger 
displays the following information: 


¢ The name of the module that contains the routine 
e The name of the routine 


e The line number at which the call was made (or at which execution is 
suspended, in the case of the current routine) 


e The corresponding PC values (the relative PC address from the 
beginning of the routine and the absolute PC address of the program) 


For example: 


DBG> SHOW CALLS 


module name routine name line rel PC abs PC 

ATEST PRODUCT 18 00000009 Q000063C 
ATEST COUNT 47 00000009 00000647 
*MY PROG MY PROG 21 OOO00000D 00000653 
DBG> 


This example indicates that execution is suspended at line 18 of routine 
PRODUCT (in module TEST), which was called from line 47 of routine 
COUNT (in module TEST), which was called from line 21 of routine 
MY_PROG (in module MY_PROG). 


2.2.8.4 Suspending Program Execution with Breakpoints 
The SET BREAK command enables you to select locations at which to 
suspend program execution (breakpoints). You can then enter commands 
to check the call stack, examine the current values of variables, and so on. 
You resume execution from a breakpoint with the GO or STEP commands. 


The following example shows a typical use of the SET BREAK command: 


DBG> SET BREAK COUNT 
DBG> GO 


break at routine PROG2\COUNT 
54: procedure COUNT (X, Y: INTEGER) ; 
DBG> 


In the example, the SET BREAK command sets a breakpoint on routine 
COUNT (at the beginning of the routine’s code); the GO command starts 
execution; when routine COUNT is encountered, execution is suspended, 
the debugger announces that the breakpoint at COUNT has been reached 
("break at... "), displays the source line (54) at which execution is 
suspended, and prompts for another command. At this breakpoint, you 
could use the STEP command to step through routine COUNT and then 
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use the EXAMINE command (discussed in Section 2.2.9.1) to check on the 
values of X and Y. 


When using the SET BREAK command, you can specify program 
locations using various kinds of address expressions (for example, line 
numbers, routine names, memory addresses, byte offsets). With high 
level languages, you typically use routine names, labels, or line numbers, 
possibly with path names to ensure uniqueness. 


Routine names and labels should be specified as they appear in the source 
code. Line numbers can be derived from either a source code display 

or a listing file. When specifying a line number, use the prefix 2LINE. 
Otherwise the debugger interprets the line number as a memory location. 
For example, the next command sets a breakpoint at line 41 of the module 
in which execution is suspended. The breakpoint causes the debugger to 
suspend further execution when the PC value is at the beginning of 

line 41. 


DBG> SET BREAK cLINE 41 


Note that you can set breakpoints only on lines that resulted in machine 
code instructions. The debugger warns you if you try to do otherwise (for 
example on a comment line). To pick a line number in a module other than 
the one in which execution is suspended, you must specify the module’s 
name in a path name. For example: 


DBG> SET BREAK SCREEN _IO\%LINE 58 


You can also use the SET BREAK command with a qualifier, but no 
parameter, to break on every line, or on every CALL instruction, and so 
on. For example: 


DBG> SET BREAK/LINE 
DBG> SET BREAK/CALL 


You can set breakpoints on events, such as exceptions, or state transitions 
in Ada tasking programs. 


You can conditionalize a breakpoint (with a "WHEN" clause) or specify 
that a list of commands be executed at the breakpoint (with a "DO" 
clause). 


To display the currently active breakpoints, enter the command SHOW 
BREAK. 


To cancel a breakpoint, enter the command CANCEL BREAK, specifying 
the program location exactly as you did when setting the breakpoint. 
CANCEL BREAK/ALL cancels all breakpoints. 


2.2.8.5 Tracing Program Execution with Tracepoints 


The SET TRACE command enables you to select locations for tracing the 
execution of your program (tracepoints), without stopping its execution. 
After setting a tracepoint, you can start execution with the GO command 
and then monitor the path of execution, checking for unexpected behavior. 
By setting a tracepoint on a routine, you can also monitor the number of 
times it is called. 
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As with breakpoints, every time a tracepoint is reached, the debugger 
issues a message and displays the source line. But the program continues 
executing, and the debugger prompt is not displayed. For example: 


DBG> SET TRACE COUNT 
DBG> GO 


trace at routine PROG2\COUNT 
54: procedure COUNT (X,Y: INTEGER) ; 


This is the only difference between a breakpoint and a tracepoint. When 
using the SET TRACE command, you specify address expressions, 
qualifiers, and optional clauses exactly as with the SET BREAK command. 


2.2.8.6 Monitoring Changes in Variables with Watchpoints 
The SET WATCH command enables you to specify program variables that 
the debugger monitors as your program executes. This process is called 
setting watchpoints. If the program modifies the value of a "watched" 
variable, the debugger suspends execution and displays information. The 
debugger monitors watchpoints continuously during program execution. 
(Note that the SET WATCH command can also be used to monitor 
arbitrary program locations, not just variables.) 


To set a watchpoint on a variable, specify the variable’s name with the 
SET WATCH command. For example, the following command sets a 
watchpoint on the variable TOTAL: 


DBG> SET WATCH TOTAL 


Subsequently, every time the program modifies the value of TOTAL, the 
watchpoint is triggered. 


The next example shows what happens when your program modifies the 
contents of a watched variable. 


DBG> SET WATCH TOTAL 
DBG> GO 


watch of SCREEN IO\TOTAL at SCREEN _IO\SLINE 13 
i3% TOTAL := TOTAL + 1; 
old value: 16 
new value: 17 
break at SCREEN IO\%SLINE 14 
14: POP (TOTAL) ; 
DBG> 


In this example, a watchpoint is set on the variable TOTAL and execution 
is started. When the value of TOTAL changes, execution is suspended. 
The debugger announces the event ("watch of ... "), identifying where 
TOTAL changed (the beginning of line 13) and the associated source 

line. The debugger then displays the old and new values and announces 
that execution has been suspended at the beginning of the next line (14). 
Finally, the debugger prompts for another command. Note that when a 
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change in a variable occurs at a point other than the beginning of a source 
line, the debugger gives the line number plus the byte offset from the 
beginning of the line. 


The technique previously described for setting watchpoints always applies 
to static variables. A static variable is associated with the same memory 
address throughout program execution. 


A variable that is allocated on the stack or in a register (a nonstatic 
variable) exists only when its defining routine is active (on the call stack). 
If you try to set a watchpoint on a nonstatic variable when its defining 
routine is not active, the debugger issues a warning: 


DBG> SET WATCH Y 
SDEBUG-W-SYMNOTACT, nonstatic variable ’Y’ is not active 
DBG> 


A convenient technique for setting a watchpoint on a nonstatic variable 
is to set a tracepoint on the defining routine, also specifying a DO clause 
to set the watchpoint whenever execution reaches the tracepoint. In 
the following example, a watchpoint is set on the nonstatic variable Y 
in routine ROUTS. After the tracepoint is triggered, the WPTTRACE 
message indicates that the nonstatic watchpoint is set. And the 
watchpoint is triggered when the value of Y changes: 


DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y) 
DBG> GO 


trace at routine MOD4\ROUT3 
sDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every 
instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\SLINE 16 


16: Y 3= 4 
old value: 3 
new value: 4 
break at MOD4\ROUT3\%LINE 17 
Lys SWAP (X,Y); 
DBG> 


When execution returns to the calling routine, the nonstatic variable is no 
longer active, so the debugger automatically cancels the watchpoint and 
issues a message to that effect. 


2.2.9 Examining and Manipulating Program Data 


2-18 


This section explains how to use the EXAMINE, DEPOSIT, and 
EVALUATE commands to display and modify the contents of variables 
and evaluate expressions. Note that before you can examine or deposit 
into a nonstatic variable, as defined in Section 2.2.8.6, its defining routine 
must be active (on the call stack). 
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2.2.9.1 Displaying the Value of a Variable 
To display the current value of a variable, use the EXAMINE command. It 
has the following form: 


EXAMINE variable-name 


The debugger recognizes the compiler-generated data type of the variable 
you specify and retrieves and formats the data accordingly. The following 
examples show some uses of the EXAMINE command. 


Examine a string variable: 


DBG> EXAMINE EMPLOYEE NAME 
PAYROLL\EMPLOYEE NAME: "Peter C. Lombardi" 
DBG> 


Examine three integer variables: 


DBG> EXAMINE WIDTH, LENGTH, AREA 


SIZE\WIDTH: 4 
SIZE\LENGTH: 7 
SIZE\AREA: 28 
DBG> 


Examine a two-dimensional array of real numbers (three per dimension): 


DBG> EXAMINE REAL ARRAY 
PROG2\REAL ARRAY 


(1,1): 27.01000 

(1,2): 31.00000 

(1,3): 12.48000 

(2,1).% 15.08000 

(2,2): 22.30000 

(2,3): 18.73000 
DBG> 


Examine element 4 of a one-dimensional array of characters: 
DBG> EXAMINE CHAR ARRAY (4) 

PROG2\CHAR_ ARRAY (4): ‘m’ 

DBG> 

Examine a record variable (COBOL example): 


DBG> EXAMINE PART 


INVENTORY \PART: 
ITEM: "WE-1247" 
PRICE: 49.95 
IN STOCK: 24 

DBG> 


Examine a record component (COBOL example): 


DBG> EXAMINE IN STOCK OF PART 
INVENTORY\IN-STOCK of PART: 

IN STOCK: 24 
DBG> 


Note that the EXAMINE command can be used with any kind of address 
expression (not just a variable name) to display the contents of a program 
location. The debugger associates certain default data types with untyped 
locations. You can override the defaults for typed and untyped locations if 
you want the data interpreted and displayed in some other data format. 
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DBG> DEPOSIT X 


2.2.9.2 Assigning a Value to a Variable 


To assign a new value to a variable, use the DEPOSIT command. It has 
the following form: 


DEPOSIT variable-name = value 


The DEPOSIT command is like an assignment statement in most 
programming languages. 


In the following examples, the DEPOSIT command assigns new values 
to different variables. The debugger checks that the value assigned, 
which can be a language expression, is consistent with the data type and 
dimensional constraints of the variable. 


Deposit a string value (it must be enclosed in quotation marks (") or 
apostrophes (’ ): 


DBG> DEPOSIT PART NUMBER = "WG-7619.3-84" 
DBG> 


Deposit an integer expression: 


DBG> DEPOSIT WIDTH = CURRENT WIDTH + 10 
DBG> 


Deposit element 12 of an array of characters (you cannot deposit an entire 
array aggregate with a single DEPOSIT command, only an element): 


DBG> DEPOSIT C_ARRAY(12) := 'K’ 
DBG> 


Deposit a record component (you cannot deposit an entire record aggregate 
with a single DEPOSIT command, only a component): 


DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 
DBG> 


Deposit an out-of-bounds value (X was declared as a positive integer): 


SDEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT 


DBG> 
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As with the EXAMINE command, you can specify any kind of address 
expression (not just a variable name) with the DEPOSIT command. You 
can override the defaults for typed and untyped locations if you want the 
data interpreted in some other data format. 


2.2.9.3 Evaluating Language Expressions 


To evaluate a language expression, use the EVALUATE command. It has 
the following form: 


EVALUATE language-expression 


The debugger recognizes the operators and expression syntax of the 
currently set language. In the following example, the value 45 is assigned 
to the integer variable WIDTH; the EVALUATE command then obtains 
the sum of the current value of WIDTH and 7: 
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DBG> DEPOSIT WIDTH := 45 
DBG> EVALUATE WIDTH + 7 
52 

DBG> 


In the next example, the values TRUE and FALSE are assigned to the 
Boolean variables WILLING and ABLE, respectively; the EVALUATE 
command then obtains the logical conjunction of these values: 


DBG> DEPOSIT WILLING := TRUE 
DBG> DEPOSIT ABLE := FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 

DBG> 


2.2.10 Controlling Access to Symbols in Your Program 


To have full access to the symbols that are associated with your program 
(variable names, routine names, source code, line numbers, and so on), you 
must compile and link the program using the /DEBUG command qualifier, 
as explained in Section 2.2.1. 


Under these conditions, the way in which the debugger handles these 
symbols is transparent to you, in most cases. However, the following two 
areas might require action: 


e Setting and canceling modules 


¢ Resolving symbol ambiguities 


2.2.10.1 Setting and Canceling Modules 
To facilitate symbol searches, the debugger loads symbol information 
from the executable image into a run-time symbol table (RST), where 
that information can be accessed efficiently. Unless symbol information 
is in the RST, the debugger does not recognize or properly interpret the 
associated symbols. 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of 
program execution. The loading process is called module setting, because 
all symbol information for a given module is loaded into the RST at one 
time. 


At debugger startup, only the module containing the image transfer 
address is set. Subsequently, whenever execution of the program is 
interrupted, the debugger sets the module that contains the routine in 
which execution is suspended. This enables you to reference the symbols 
that should be visible at that location. 


If you try to reference a symbol in a module that has not been set, the 
debugger warns you that the symbol is not in the RST. For example: 


DBG> EXAMINE K 


SDEBUG-W-NOSYMBOL, symbol ’K’ is not in symbol table 
DBG> 
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You must then use the SET MODULE command to set the module 
containing that symbol explicitly: 


DBG> SET MODULE MOD3 
DBG> EXAMINE K 
MOD3\ROUT2\K: 26 
DBG> 


The SHOW MODULE command lists the modules of your. program and 
identifies which modules are set. 


Note that dynamic module setting can slow the debugger down as more 
and more modules are set. If performance becomes a problem, you can use 
the CANCEL MODULE command to reduce the number of set modules, 
or you can disable dynamic module setting by entering the command SET 
MODE NODYNAMIC (SET MODE DYNAMIC enables dynamic module 
setting). 


2.2.10.2 Resolving Symbol Ambiguities 


Symbol ambiguities can occur when a symbol (for example, a variable 
name X) is defined in more than one routine or other program unit. 


In most cases, the debugger resolves symbol ambiguities automatically. 
First it uses the scope and visibility rules of the currently set language. In 
addition, because the debugger permits you to specify symbols in arbitrary 
modules (to set breakpoints and so on), the debugger uses the ordering of 
routine calls on the call stack to resolve symbol ambiguities. 


If the debugger cannot resolve a symbol ambiguity, it issues a message. 
For example: 


DBG> EXAMINE Y 
SDEBUG-W-NOUNIQUE, symbol ’Y’ is not unique 
DBG> 


You can then use a path name prefix to uniquely specify a declaration of 
the given symbol. First, use the SHOW SYMBOL command to identify 
all path names associated with the given symbol (corresponding to all 
declarations of that symbol) that are currently loaded in the RST. Then 
use the desired path name prefix when referencing the symbol. For 
example: 


DBG> SHOW SYMBOL Y 

data MOD7\ROUT3\BLOCK1L\Y 
data MOD4\ROUT2\Y 

DBG> EXAMINE MOD4\ROUT2\Y 
MOD4\ROUT2\Y: 12 

DBG> 


If you need to refer to a particular declaration of Y repeatedly, use the 
SET SCOPE command to establish a new default scope for symbol lookup. 
Then, references to Y without a path name prefix specify the declaration of 
Y that is visible in the new scope. For example: 


DBG> SET SCOPE MOD4\ROUT2 
DBG> EXAMINE Y 
MOD4\ROUT2\Y: 12 

DBG> 
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To display the current scope for symbol lookup, use the SHOW SCOPE 
command. To restore the default scope, use the CANCEL SCOPE 
command. 





2.3 A Sample Debugging Session 


This section walks you through a debugging session with a simple 
FORTRAN program which contains a logic error (see Example 2-1). 
Compiler-assigned line numbers have been added in the example so that 
you can identify the source lines referenced in the discussion. 


The program, called SQUARES, performs the following functions: 


1 Reads a sequence of integer numbers from a data file and saves these 
numbers in the array INARR (lines 4 and 5). 


2 Enters a loop in which it copies the square of each non-zero integer 
into another array OUTARR (lines 8 through 13). 


3 Prints the number of non-zero elements in the original sequence and 
the square of each such element (lines 16 through 21). 


Example 2-1 Sample Program SQUARES 


13 INTEGER INARR(20), OUTARR (20) 

22°C 

oe -C ---~Read the input array from the data file. 

4: OPEN (UNIT=8, FILE=’DATAFILE.DAT’, STATUS=’ OLD’ ) 
54 READ (8,*) N, (INARR(I), I=1,N) 

63; 

ae ---Square all non-zero elements and store in OUTARR. 
8: K = 0 

93 DO 10 I= 1, N 
10: IF (INARR(I) .NE. 0) THEN 
Las OUTARR(K) = INARR(I) **2 
yee ENDIF 
Ne 9 10 CONTINUE 
LAS: GC 
Loe: C ---Print the squared output values. Then stop. 
16: PRINT 20, K 
urs 20 FORMAT(’ Number of non-zero elements is’,I4) 
18: DO 40 I=1, K 
LS PRINT 30, I, OUTARR(T) 
20% 30 FORMAT (’ Element’,1I4,’ has value’,I6) 
a 40 CONTINUE 
22% END 


When you run SQUARES, it produces the following output, regardless of 
the number of non-zero elements in the data file: 


S$ RUN SQUARES 
Number of non-zero elements is 0 


The error in the program is that variable K, which keeps track of the 
current index into OUTARR, is not incremented in the loop on lines 9 
through 13. The statement K = K + 1 should be inserted just before 
line 11. 
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Example 2—2 shows how to compile, link, and run the program to 
invoke the debugger, and then how to use the debugger to find the error. 
Comments, keyed to the callouts, follow the example. 


Example 2-2 Sample Debugging Session Using Program SQUARES 





$ FORTRAN/DEBUG/NOOPTIMIZE SQUARFS @ 

$ LINK/DEBUG SQUARES 

$ SHOW LOGICAL DBGSPROCESS ®@ 

SSHOW-S-NOTRAN, no translation for logical name DBGSPROCESS 


$ RUN SQUARES 4) 
VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is FORTRAN, module set to SQUARESSMAIN 
DBG> STEP 4 
stepped to SQUARESSMAIN\SLINE 9 


8 DO 10 I= 1, N 
DBG> EXAMINE N,K 
SQUARESSMAIN\N: 9 
SQUARESSMAIN\K: 0 


DBG> STEP 2 
stepped to SQUARESSMAIN\SLINE 11 


ids OUTARR(K) = INARR(I) **2 
DBG> EXAMINE I,K 
SQUARESSMAIN\TI: 1 
SQUARESSMAIN\K: 0 
DBG> DEPOSIT K=1 @ 
DBG> SET TRACE/SILENT %LINE 11 DO (DEPOSIT K = K + 1) © 
DBG> GO 
Number of non-zero elements is 4 
Element 1 has value 16 
Element 2 has value 36 
Element 3 has value 9 
Element 4 has value 49 


*DEBUG-I-EXITSTATUS, is ’SYSTEM-S-NORMAL, normal successful completion’ 
DBG> EXIT @ 
$ EDIT SQUARES.FOR ® 


LO: IF (INARR(I) .NE. 0) THEN 


oi K = K+ 1 
12: OUTARR(K) = INARR(I) **2 
13% ENDIF 


$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES ® 
$ LINK/DEBUG SQUARES 
$ RUN SQUARES 


DBG> SET BREAK <cLINE 12 DO (EXAMINE I,K) ® 
DBG> GO 





(continued on next page) 
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Example 2-2 (Cont.) Sample Debugging Session Using Program SQUARES 





SQUARESSMAIN\I: 
SQUARESSMAIN\K: 


DBG> GO 


SQUARESSMAIN\TI: 
SQUARESSMAIN\K: 


DBG> GO 


SQUARESSMAIN\TI: 
SQUARESSMAIN\K: 


DBG> 


N NH 


The following comments apply to the callouts in Example 2-2. 
Example 2—1 shows the program that is being debugged. 


@ The /DEBUG qualifier on the FORTRAN command directs the compiler 


to write the symbol information associated with SQUARES into the 
object module, SQUARES.OBJ, in addition to the code and data for the 


program. 


The /NOOPTIMIZE qualifier disables optimization by the FORTRAN 
compiler, to ensure that the executable code match the source code of 
the program. Debugging optimized code can be confusing because the 
contents of some program locations might be inconsistent with what 
you would expect from viewing the source code. 


The /DEBUG qualifier on the LINK command causes the linker to 
include all symbol information that is contained in FORMS.OBJ in the 
executable image. The qualifier also causes the VMS image activator 
to start the debugger at run time. 


The debugger can be invoked in either the default configuration or 
the multiprocess configuration, depending on the definition of the 
logical name DBG$PROCESS. In this example, the command SHOW 
LOGICAL DBG$PROCESS shows that DBG$PROCESS is undefined, 
indicating that the default configuration is in effect. This is the correct 
configuration for a program like SQUARES that runs in only one 
process. 


The RUN command invokes the debugger (if you have used the 
/DEBUG qualifier with the LINK command). 


When the debugger is invoked, it displays an informational message 
and the debugger prompt, DBG>. You can now enter debugger 
commands. Execution is initially suspended at the start of the main 
program unit (line 1 of program SQUARES, in this example). 


You decide to test the values of variables N and K after the READ 
statement has been executed and the value 0 has been assigned to K. 
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The command STEP 4 executes 4 source lines of the program. 
Execution is now suspended at line 9. Note that the STEP command 
ignores source lines that do not result in executable code; also, by 
default, the debugger identifies the source line at which execution is 
suspended. 


The command EXAMINE N, K displays the current values of N and K. 
Their values are correct at this point in the execution of the program. 


The command STEP 2 executes the program into the loop that copies 
and squares all non-zero elements of INARR into OUTARR. 


The command EXAMINE I,K displays the current values of J and K. 


I has the expected value, 1. But K has the value 0 instead of 1, which 
is the expected value. Now you can see the error in the program: K 
should be incremented in the loop just before it is used in line 11. 


The DEPOSIT command assigns K the value it should have now: 1. 


The SET TRACE command is now used to patch the program so that 
the value of K is incremented automatically in the loop. The command 
sets a tracepoint that triggers every time execution reaches line 11: 


e The /SILENT qualifier suppresses the "trace at" message that 
would otherwise appear each time line 11 is executed. 


¢ The DO clause issues the command DEPOSIT K = K + 1 every 
time the tracepoint is triggered. 


To test the patch, the GO command starts execution from the current 
location. 


The program output shows that the patched program works properly. 
The EXITSTATUS diagnostic message shows that the program 
executed to completion. 


The EXIT command ends the debugging session, returning control to 
DCL level. 


The source file is edited to add K = K + 1 after line 10, as shown. 
(Compiler-assigned line numbers have been added to clarify the 
example.) 


The program is compiled, linked, and executed again under debugger 
control, to check that it runs correctly. 


The SET BREAK command sets a breakpoint that triggers every time 
line 12 is executed. The DO clause displays the values of J and K 
automatically when the breakpoint triggers. 


The GO command starts execution. 


At the first breakpoint, the value of K is 1, indicating that the program 
is running correctly so far. Each additional GO command shows the 
current values of J and K. After two GO commands, K is now 3, as 
expected, but note that J is 4. The reason is that one of the INARR 
elements was zero so that lines 11 and 12 were not executed (and K 
was not incremented) for that iteration of the DO loop. This confirms 
that the program is running correctly. 
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2.4 Debugger Command Summary 


The following sections list all the debugger commands and any related 
DCL commands in functional groupings, along with brief descriptions. 
During a debugging session, you can get online help on all debugger 
commands and their qualifiers by typing HELP. 


2.4.1. Starting and Ending a Debugging Session 


The following commands are used to start, interrupt, and end a debugging 


session: 


RUN' 
RUN/[NO]DEBUG' 
EXIT, CTRL/Z 
QUIT 


CTRL/C 


(SET,SHOW) ABORT_KEY 


CTRL/Y—DEBUG' 


ATTACH 


SPAWN 


Invokes the debugger if LINK/DEBUG was 
used 


Controls whether the debugger is invoked 
when the program is executed 


Ends a debugging session, executing all exit 
handlers 


Ends a debugging session without executing 
any exit handlers declared in the program 


Aborts program execution or a debugger 
command without interrupting the debugging 
session 


Assigns the default CTRL/C abort function to 
another CTRL—key sequence, identifies the 
CTRL—key sequence currently defined for the 
abort function 


Interrupts a program that is running without 
debugger control and invokes the debugger 


Passes control of your terminal from the 
current process to another process 


Creates a subprocess, enabling you to 
execute DCL commands without ending a 
debugging session or losing your debugging 
context 


'This is a DCL command, not a debugger command. 


2.4.2 Controlling and Monitoring Program Execution 


The following commands are used to control and monitor program 


execution: 


GO 
STEP 


(SET,SHOW) STEP 


(SET,SSHOW,CANCEL) BREAK 


Starts or resumes program execution 


Executes the program up to the next line, 
instruction, or specified instruction 


(Establishes, displays) the default qualifiers for 
the STEP command 


(Sets, displays, cancels) breakpoints 
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(SET,SHOW,CANCEL) TRACE 
(SET,SHOW,CANCEL) WATCH 
SHOW CALLS 
SHOW STACK 


CALL 


2.4.3. Examining and Manipulating Data 


The following commands are used to examine and manipulate data: 


EXAMINE 


SET MODE [NOJOPERANDS 


DEPOSIT 


EVALUATE 


2.4.4 Controlling Type Selection and Radix 


The following commands are used to control type selection and radix: 


(SET,SSHOW,CANCEL) RADIX 


(SET,SSHOW,CANCEL) TYPE 


SET MODE [NO]G_FLOAT 


(Sets, displays, cancels) tracepoints 
(Sets, displays, cancels) watchpoints 
Identifies the currently active routine calls 


Gives additional information about the 
currently active routine calls 


Calls a routine 


Displays the value of a variable or the contents 
of a program location 


Controls whether the address and contents of 
the instruction operands are displayed when 
you examine an instruction 


Changes the value of a variable or the 
contents of a program location 


Evaluates a language or address expression 


(Establishes, displays, restores) the radix for 
data entry and display 


(Establishes, displays, restores) the type for 
program locations that are not associated with 
a compiler generated type 


Controls whether double-precision floating- 
point constants are interpreted as G_FLOAT 
or D_FLOAT 


2.4.5 Controlling Symbol Lookup and Symbolization 


The following commands are used to control symbol lookup and 
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symbolization: 


SHOW SYMBOL 
(SET,SHOW,CANCEL) MODULE 


(SET,SHOW,CANCEL) IMAGE 


SET MODE [NO]DYNAMIC 


Displays symbols in your program 


Sets a module by loading its symbol 
information into the debugger’s symbol table, 
identifies, cancels a set module 


Sets a shareable image by loading data 
structures into the debugger’s symbol table, 
identifies, cancels a set image 


Controls whether or not modules and 
shareable images are set automatically when 
the debugger interrupts execution 
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(SET,SSHOW,CANCEL) SCOPE 
SYMBOLIZE 


SET MODE [NOJLINE 


SET MODE [NO]SYMBOLIC 


Displaying Source Code 


2.4 Debugger Command Summary 


(Establishes, displays, restores) the scope for 
symbol lookup 


Converts a memory address to a symbolic 
address expression 


Controls whether program locations are 
displayed in terms of line numbers or routine- 
name + byte offset 


Controls whether program locations are 
displayed symbolically or in terms of numeric 
addresses 


The following commands are used to control the display of source code: 


TYPE 
EXAMINE/SOURCE 


SEARCH 
(SET,SHOW) SEARCH 


SET STEP [NOJSOURCE 


(SET,SHOW) MARGINS 
(SET,SHOW,CANCEL) SOURCE 


(SET,SHOW) 
MAX_SOURCE_FILES 


Using Screen Mode 


Displays lines of source code 


Displays the source code at the location 
specified by the address expression 


Searches the source code for the specified 
string 


(Establishes, displays) the default qualifiers for 
the SEARCH command 


Enables/disables the display of source code 
after a STEP command has been executed or 
at a breakpoint, tracepoint, or watchpoint 


(Establishes, displays) the left and right margin 
settings for displaying source code 


(Creates, displays, cancels) a source directory 
search list 


(Establishes, displays) the maximum number 
of source files that can be kept open at one 
time (but does not limit the number of source 
files that can be opened) 


The following commands are used to control screen mode and screen 


displays: 

SET MODE [NO]JSCREEN 
DISPLAY 

SCROLL 

EXPAND 

MOVE 

(SHOW,CANCEL) DISPLAY 
(SET,SHOW,CANCEL) WINDOW 


Enables/disables screen mode 
Creates or modifies a display 
Scrolls a display 

Expands or contracts a display 
Moves a display across the screen 
(Identifies, deletes) a display 


(Creates, identifies, deletes) a window 
definition 
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SELECT 
SHOW SELECT 


SAVE 
EXTRACT 


(SET,SSHOW) TERMINAL 


SET MODE [NO]SCROLL 


CTRL/W,DISPLAY/REFRESH 


2.4.8 Editing Source Code 


The following commands are used to control source editing from a 


debugging session: 


EDIT 
(SET,SHOW) EDITOR 


2.4.9 Defining Symbols 


The following commands are used to define and delete symbols for 


addresses, commands, or values: 
DEFINE 


DELETE 
(SET,SHOW) DEFINE 


SHOW SYMBOL/DEFINED 


2.4.10 Using Keypad Mode 


The following commands are used to control keypad mode and key 
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definitions: 


SET MODE [NO]KEYPAD 
DEFINE/KEY 
DELETE/KEY 

SET KEY 

SHOW KEY 


Selects a display for a display attribute 


Identifies the displays selected for each of the 
display attributes 


Saves the current contents of a display into 
another display 


Saves a display or the current screen state 
into a file 


(Establishes, displays) the terminal screen 
height and width that the debugger uses when 
it formats displays and other output 


Controls whether an output display is updated 
line by line or once per command 


Refreshes the screen 


Invokes an editor during a debugging session 


(Establishes, identifies) the editor invoked by 
the EDIT command 


Defines a symbol as an address, command, or 
value 


Deletes symbol definitions 


(Establishes, displays) the default qualifier for 
the DEFINE command 


Identifies symbols that have been defined with 
the DEFINE command 


Enables/disables keypad mode 
Creates key definitions 

Deletes key definitions 

Establishes the key definition state 
Displays key definitions 
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2.4.11 Using Command Procedures, Log Files, and Initialization Files 


The following commands are used with command procedures and log files: 


@file-spec 
(SET,SSHOW) ATSIGN 
DECLARE 


(SET,SHOW) LOG 
SET OUTPUT [NO]LOG 


SET OUTPUT [NO]JSCREEN_LOG 


SET OUTPUT [NO]VERIFY 


SHOW OUTPUT 


2.4.12 Using Control Structures 


Executes a command procedure 


(Establishes, displays) the default file 
specification that the debugger uses to search 
for command procedures 


Defines parameters to be passed to command 
procedures 

(Specifies, identifies) the debugger log file 
Controls whether a debugging session is 
logged 

Controls whether, in screen mode, the screen 
contents are logged as the screen is updated 


Controls whether debugger commands 
are displayed as a command procedure is 
executed 


Identifies the current output options 
established by the SET OUTPUT command 


The following commands are used to establish conditional and looping 
structures for debugger commands: 


FOR 


IF 
REPEAT 


WHILE 


EXITLOOP 


2.4.13 Debugging Multiprocess Programs 


Executes a list of commands while 
incrementing a variable 


Executes a list of commands conditionally 


Executes a list of commands a specified 
number of times 

Executes a list of commands while a condition 
is true 

Exits an enclosing WHILE, REPEAT, or FOR 
loop 


The following commands are used for debugging multiprocess programs: 


CONNECT 
DEFINE/PROCESS_GROUP 


DO 


Brings a process under debugger control 


Assigns a symbolic name to a list of process 
specifications 


Executes commands in the context of one or 
more processes 
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SET MODE [NO]INTERRUPT 


(SET,SSHOW) PROCESS 


2.4.14 Additional Commands 


The following commands are used for miscellaneous purposes: 
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(DISABLE,ENABLE,SHOW) AST 


(SET,SSHOW) EVENT_FACILITY 


(SET,SHOW) LANGUAGE 
SET MODE [NO]SEPARATE 


SET OUTPUT [NO]TERMINAL 


SET PROMPT 
(SET,SHOW) TASK 


(SET,SSHOW) VECTOR_MODE 


SHOW EXIT_HANDLERS 


SHOW MODE 


SHOW OUTPUT 


SYNCHRONIZE VECTOR_MODE 


Controls whether execution is interrupted in 
other processes when it is suspended in some 
process 


Modifies the multiprocess debugging 
environment, displays process information 


(Disables, enables) the delivery of ASTs in the 
program, identifies whether delivery is enabled 
or disabled 


(Establishes, identifies) the current run-time 
facility for language-specific events 


(Establishes, identifies) the current language 


Controls whether the debugger, when used 
on a workstation running VWS, creates a 
separate window for debugger input and 
output 


Controls whether debugger output, except 
for diagnostic messages, is displayed or 
suppressed 


Specifies the debugger prompt 


Modifies the tasking environment, displays 
task information 


Enables or disables a debugger vector mode 
option, identifies the current vector mode 
option (for vectorized programs). 


Identifies the exit handlers declared in the 
program 

Identifies the current debugger modes 
established by the SET MODE command 
(for example, screen mode, step mode) 


Identifies the current output options 
established by the SET OUTPUT command 


Forces immediate synchronization between the 
scalar and vector processors (for vectorized 
programs) 


3 Controlling and Monitoring Program Execution 


This chapter describes the options for invoking the debugger and for 
controlling and monitoring program execution while debugging. 


The chapter includes information that is common to all programs. 


See Chapter 10 for additional information specific to multiprocess 
programs. 


See Chapter 11 for additional information specific to vectorized 
programs. 


3.1 Starting and Ending a Debugging Session 


This section explains how to do the following: 


Compile and link your program so you can invoke the debugger 


Start, interrupt, resume, and end a debugging session 


3.1.1. Invoking the Debugger with the DCL RUN Command 


The usual way to invoke the debugger is as follows: 


1 


Compile your program using the /DEBUG and /NOOPTIMIZE (or 
equivalent) qualifiers with the DCL compiler command (consult your 
language documentation to determine the compiler command defaults). 


Link your program using the /DEBUG qualifier with the DCL LINK 
command. 


Use the DCL command SHOW LOGICAL DBG$PROCESS to make 
sure that the value of the logical name DBG$PROCESS is appropriate 
for the type of program you are debugging (see Section 10.2.1): 


e If you are debugging a program that runs in only one process, 
DBG$PROCESS should be either undefined or should have the 
value DEFAULT. 


e If you are debugging a program that runs in more than one 
process, DBG$PROCESS should have the value MULTIPROCESS. 


Execute your program using the DCL RUN command. The debugger 
initially takes control of the program and prompts for commands. 


Note that you cannot run a program under debugger control over a 
DECnet link. Both the image to be debugged and the debugger must 
reside on the same node. 
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The following example illustrates the previous steps with a simple Pascal 
program, INVENTORY, that consists of two compilation units whose 
source code is in two separate files, FORMS.PAS and INVENTORY.PAS. 
INVENTORY is the main program unit. 


S$ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 
S$ RUN INVENTORY 


VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is PASCAL, module set to INVENTORY 
DBG> 


When the debugger first takes control, it does the following: 
¢ Displays its banner. 


e Sets the language-dependent parameters to the language of the main 
program (the module that contains the image transfer address). The 
"INITIAL" message identifies the language to which the debugging 
session is initialized and the name of the main program (Pascal and 
INVENTORY, respectively, in the previous example). See Section 4.1.8 
and Section 4.1.9 for more information about language-dependent 
parameters. 


e Executes any user-defined initialization file (see Section 8.2). 


e Suspends execution at the beginning of the main program. The DBG> 
prompt, which is displayed whenever the debugger suspends execution, 
indicates that you can now enter debugger commands. 


In some cases the debugger suspends execution before the beginning of the 
main program and displays the following additional message: 


%SDEBUG-I-NOTATMAIN, type GO to get to start of main program 
See Section 9.3 for an explanation of this message. 


The effect of the qualifiers used with the compiler command (PASCAL, in 
this example) and the LINK command is as follows. 


The /DEBUG qualifier on the compiler command loads the debugger 
symbol information associated with each compilation unit into its object 
module. This symbol information enables you to use, in debugger 
commands, the names of variables, routines, labels, and other symbols 

as they appear in the source code. By specifying options with the /DEBUG 
qualifier, you can control the level of symbolic information provided (see 
Section 5.1.1). This qualifier does not affect whether the debugger is 
invoked or how it is invoked. 


Most compilers optimize code to.reduce the size of the program and make 
it run faster. For example, invariant expressions are removed from DO 
loops so that they are evaluated only once at run time; also, some memory 
locations might be allocated to different variables at different points in 
the program. The /NOOPTIMIZE (or equivalent) qualifier ensures that 
the code is not optimized and, therefore, that the contents of all program 
locations are consistent with what you would expect from looking at the 
source code. Section 9.1 describes some of the effects of optimization. 
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Note also another possible cause of unexpected behavior. The debugger 
and your program share the same address space. In some rare cases, this 
can cause the debugger to affect how your program executes. Section 3.7 
explains how the debugger controls execution and the possible sources of 
interference. 


The /DEBUG qualifier on the LINK command provides the following 
functions: 


¢ Copies the debugger symbol information from the object modules being 
linked into the debug symbol table (DST) and puts the DST in the 
executable image. 


e Directs the image activator to pass control to the debugger when you 
subsequently execute the image with the RUN command. 


See Section 5.1.3 for more details on how the LINK command controls 
symbol information. 


Even if you have compiled and linked an image with the /DEBUG 
command qualifier, you can execute that image normally, without it 
being under debugger control. To do so, use the /NODEBUG qualifier on 
the DCL RUN command. For example: 


S$ RUN/NODEBUG INVENTORY 


This is convenient for checking your program after you think it is error 
free. But the data required by the debugger still occupies space within 
the executable image. So, when you think your program is correct, you 
might want to link your program again without the /DEBUG qualifier. 

This creates an image with only traceback data in the DST, to use less 
disk space. 


Table 3—1 summarizes how to control debugger activation by means of 
LINK and RUN command qualifiers. Note that the LINK command 
qualifiers ([NO]DEBUG and /[NOJTRACEBACK affect not only debugger 
activation but also the level of symbol information provided. 


Table 3-1 Controlling Debugger Activation with the LINK and RUN Commands 


LINK Command 
Qualifier 
/DEBUG 


/TRACEBACK or 
/NODEBUG? 


/NOTRACEBACK 


To Run Program To Run Program Maximum Symbol Information 
With Debugger Without Debugger Available! 

RUN RUN/NODEBUG Full 

RUN/DEBUG RUN Only traceback?® 

Cannot RUN None 


'The level of symbol information available while debugging is controlled both by the compile command qualifier and the LINK 
command qualifier (see Section 5.1). 


2LINK/TRACEBACK (or LINK/NODEBUG) is a LINK command default. 


3Traceback information includes compiler-generated line numbers and the names of routines and modules (compilation units). 
This symbol information is used by the VMS traceback condition handler to identify the PC value and the active calls when a 
run-time error has occurred. The information is also used by the debugger SHOW CALLS command (see Section 2.2.8.3). 
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3.1.2. Invoking the Debugger with the DCL DEBUG Command 


You can invoke the debugger while your program is executing freely—for 
example, if you suspect that the program might be in an infinite loop or if 
you see erroneous output. 


To invoke the debugger in this manner, proceed as follows: 


1 Compile and link the program with the /DEBUG command qualifier, 
as described in the previous section (you can also use LINK 
/TRACEBACK, but only traceback symbols are then available while 
you debug). 


2 Enter the DCL command RUN/NODEBUG to execute the program 
without debugger control. 


3 Press CTRL/Y to interrupt the executing program. Control then passes 
to the DCL command interpreter. 


4 Enter the DCL command DEBUG to activate the debugger. It displays 
its banner, sets the language-dependent parameters to the language 
of the module where execution was interrupted, executes any user- 
defined initialization file, and prompts for commands. Usually you will 
not know where execution was interrupted. Enter the SHOW CALLS 
command to identify the current PC value and the sequence of routine 
calls on the call stack (the SHOW CALLS command is described in 
Section 2.2.8.3). 


For example: 


S$ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 
$ RUN/NODEBUG INVENTORY 


Interrupt 


S DEBUG 
VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is PASCAL, module set to INVENTORY 
DBG> SHOW CALLS 


Interrupting a running program with CTRL/Y and then invoking the 
debugger with the DEBUG command is useful under the following 
conditions: 


e ‘Your program is in an infinite loop. 


e After entering the RUN/NODEBUG command, you decide that you 
want debugger control. 


3.1.3 
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¢ You have not specified the /DEBUG command qualifier at compile 
time, link time, or run time but want to debug your running program. 
In this case, traceback information is the only symbol information 
available for debugging. 


Ending a Debugging Session 


To end a debugging session in an orderly manner, use the EXIT or QUIT 
commands, or press CTRL/Z. These commands invoke the debugger exit 
handlers to close log files, restore the screen and keypad states, and so on. 


The EXIT command and CTRL/Z have the same effect. The QUIT 
command is like the EXIT command or CTRL/Z, except that the EXIT 
command and CTRL/Z also execute any exit handlers that are declared in 
your program; the QUIT command does not. 


Interrupting and Resuming a Debugging Session 


As explained in Section 2.2.5, use CTRL/C (not CTRL/Y) to abort the 
execution of a debugger command or to interrupt program execution. This 
is useful if a command takes a long time to complete or your program is 
in an infinite loop. Control is returned to the debugger rather than to the 
DCL command interpreter. 


The debugger SPAWN and ATTACH commands enable you to interrupt a 
debugging session from the debugger prompt, enter DCL commands, and 


return to the debugger prompt. These commands function essentially like 
the DCL SPAWN and ATTACH commands. 


Use the debugger SPAWN command to create a subprocess. Use 
the debugger ATTACH command to attach to an existing process or 
subprocess. 


You can enter the SPAWN command with or without specifying a DCL 
command as parameter. If you specify a DCL command, it is executed in a 
subprocess (if the DCL command invokes a utility, that utility is invoked 
in a subprocess). Control returns to the debugging session when the DCL 
command terminates (or when you exit the utility). The following example 
illustrates spawning the DCL DIRECTORY command. 


DBG> SPAWN DIR [JONES.PROJECT2]*.FOR 


SDEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 
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The next example illustrates spawning the DCL MAIL command, which 
invokes the MAIL utility: 


DBG> SPAWN MAIL 
MAIL> READ/NEW 


MAIL> EXIT 
SDEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 


If you enter the SPAWN command without specifying a parameter, a 
subprocess is created, and you can then enter DCL commands. Either 
logging out of the subprocess or attaching to the parent process (with 
the DCL ATTACH command) returns you to the debugging session. For 
example: 


DBG> SPAWN 
$ RUN PROG2 


$ ATTACH JONES 1 
SDEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 


If you plan to go back and forth several times between your debugging 
session and a spawned subprocess (which might be another debugging 
session), use the debugger ATTACH command to attach to that subprocess. 
Use the DCL ATTACH command to return to the parent process. Because 
you do not create a new subprocess every time you leave the debugger, you 
use system resources more efficiently. 


If you are running two debugging sessions simultaneously, you can define 
a new debugger prompt for one of the sessions with the SET PROMPT 
command. This helps you to differentiate the sessions. 


3.3 Commands Used to Execute the Program 


3-6 


Only four debugger commands can be used to execute your program: GO, 
STEP, CALL, and EXIT (Gif your program has exit handlers). 


As indicated in Section 2.2.8.1, GO and STEP are the basic commands 
for starting and resuming program execution. The STEP command is 
discussed further in Section 3.4. 


During a debugging session, routines are executed as they are called 
during the execution of a program. The CALL command enables you to 
arbitrarily call and execute a routine that was linked with your program. 
This command is discussed in Section 8.7. 


The EXIT command was discussed in Section 3.1.3, in conjunction with 
ending a debugging session. Because it executes any exit handlers in your 
program, it is also useful for debugging exit handlers (see Section 9.5). 
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When using any of these four commands, keep in mind that program 
execution can be interrupted or stopped by any of the following events: 


e The program terminates. 
¢ A breakpoint is reached. 

¢ A watchpoint is activated. 
e An exception is signaled. 
e You press CTRL/C. 


3.4 Executing the Program by Step Unit 


The STEP command (probably the most frequently used debugger 
command) enables you to execute your program in small increments 
called step units. 


By default, a step unit is an executable line of source code. In the 
following example, the STEP command executes one line, reports the 
action ("stepped to... "), and displays the line number (27) and source 
code of the next line to be executed: 


DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
27: Kote, ke 

DBG> 


Execution is now suspended at the first machine code instruction for line 
27 of module TEST. Line 27 is in COUNT, a routine within module TEST. 


The STEP command can also execute several source lines at a time. If 
you specify a positive integer as a parameter, the STEP command executes 
that number of lines. In the following example, the STEP command 
executes the next three lines: 


DBG> STEP 3 

stepped to TEST\COUNT\SLINE 34 
34; SWAP (X,Y); 

DBG> 


Note that only those source lines for which code instructions were 
generated by the compiler are recognized as executable lines by the 
debugger. The debugger skips over any other lines—for example, comment 
lines. Also, if a line has more than one statement on it, the debugger 
executes all the statements on that line as part of the single step. 


Source lines are displayed by default after stepping if they are available 
for the module being debugged. Source lines are not available if you are 
stepping in code that has not been compiled or linked with the /DEBUG 
qualifier (for example, a shareable image routine). If source lines are 
available, you can control their display with the SET STEP [NO]JSOURCE 
command and the /[NOJSOURCE qualifier of the STEP command. See 
Chapter 6 for information about how to control the display of source code 
in general and in particular after stepping. 
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3.4.1. Changing the STEP Command Behavior 


The default behavior of the STEP command can be altered in the following 
two ways: 


e By specifying a STEP command qualifier—for example, STEP 
INSTRUCTION. 


e By establishing a new default qualifier with the SET STEP 
command—for example, SET STEP INSTRUCTION. 


In the following example, the command STEP/INSTRUCTION executes 
the next instruction rather than the next line (STEP/LINE is the default 
behavior). The debugger displays the source line (10) associated with the 
new PC value (instruction TSTL): 


DBG> STEP/INSTRUCTION 

stepped to SQUARESSMAIN\SLINE 10+4: TSTL W*~-164 (R11) [RO] 
10% IF(INARR(I) .NE. Q) THEN 

DBG> 


After the STEP/INSTRUCTION command executes, subsequent STEP 
commands revert to the default behavior. 


In contrast, the SET STEP command enables you to establish new defaults 
for the STEP command. These defaults remain in effect until another 
SET STEP command is entered. For example, the command SET STEP 
INSTRUCTION causes subsequent STEP commands to behave like STEP 
/INSTRUCTION (SET STEP LINE causes subsequent STEP commands to 
behave like STEP/LINE). 


There is a SET STEP command parameter for each STEP command 
qualifier. 


You can override the current STEP command defaults for the duration of 
a single STEP command by specifying other qualifiers. Use the SHOW 
STEP command to identify the current STEP command defaults. 


3.4.2 Stepping into and over Routines 
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By default, when the PC is at a call statement and you enter the STEP 
command, the debugger steps "over" the called routine. Although the 
routine is executed, execution is not suspended within the routine but, 
rather, on the beginning of the line that follows the call statement. When 
stepping by instruction, execution is suspended on the instruction that 
follows a called routine’s RET (return from routine) instruction. 


To step into a called routine when the PC is at a call statement, enter the 
STEP/INTO command. The following example shows how to step into the 
routine PRODUCT, which is called from routine COUNT of module TEST: 


DBG> STEP 
stepped to TEST\COUNT\SLINE 18 
a 3 3 AREA := PRODUCT (LENGTH, WIDTH) ; 
DBG> STEP/INTO 
stepped to routine TEST\PRODUCT 
6: function PRODUCT(X,Y : INTEGER) return INTEGER is 
DBG> 
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To return to the calling routine from any point within the called routine, 
use the STEP/RETURN command. It causes the debugger to step to 
the RET instruction of the routine being executed. A subsequent STEP 
command brings you back to the statement that follows the routine call. 
For example: 


DBG> STEP/RETURN 

stepped on return from TEST\PRODUCT\SLINE 11 to TEST\PRODUCT\SLINE 15+4 
15s end PRODUCT; 

DBG> STEP 

stepped to TEST\COUNT\%SLINE 19 
19: LENGTH := LENGTH + 1; 

DBG> 


To step into several routines, enter the command SET STEP INTO to 
change the default behavior of the STEP command from STEP/OVER to 
STEP/INTO: 


DBG> SET STEP INTO 


As a result of this command, when the PC is at a call statement, a STEP 
command suspends execution within the called routine. If you later want 
to step over routine calls, enter the command SET STEP OVER. 


When SET STEP INTO is in effect, you can qualify the kinds of called 
routines that the debugger is stepping into by specifying any of the 
following parameters with the SET STEP command: 


e [NO}JSB—controls whether to step into routines called by JSB 
instructions. 


e¢ [NO]JSHARE—controls whether to step into called routines in 
shareable images. 


e [NO]SYSTEM—controls whether to step into called system routines. 


These parameters make it possible to step into application-defined routines 
and automatically step over system routines, and so on. For example, the 
following command directs the debugger to step into called routines in 
user space only. The debugger steps over routines in system space and in 
shareable images. 


DBG> SET STEP INTO, NOSYSTEM, NOSHARE 


3.5 Suspending and Tracing Execution with Breakpoints and Tracepoints 


This section discusses use of the SET BREAK and SET TRACE commands 
to, respectively, suspend and trace program execution. The commands are 
discussed together because of their similarities. 


SET BREAK Command Overview 


The SET BREAK command enables you to specify program locations or 
events at which to suspend program execution (breakpoints). After setting 
a breakpoint, you can start or resume program execution with the GO 
command, letting the program run until the specified location or condition 
is reached. When the breakpoint is triggered, the debugger suspends 
execution, identifies the breakpoint, and displays the DBG> prompt. You 
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can then enter debugger commands—for example, to determine where you 
are (with the SHOW CALLS command), step into a routine, examine or 
modify variables, and so on. 


The syntax of the SET BREAK command is as follows: 


SET BREAK[/qualifier[, ... ]] [address-expression[, ... ]] 
[WHEN (conditional-expression)] 
[DO (command[;... ])] 


The following example shows a typical use of the SET BREAK command 
and illustrates the general default behavior of the debugger at a 
breakpoint. 


In this example, the SET BREAK command sets a breakpoint on routine 
COUNT (at the beginning of the routine’s code). The GO command 
starts execution. When routine COUNT is encountered, execution is 
suspended, the debugger announces that the breakpoint at COUNT 

has been reached ("break at... "), displays the source line (54) where 
execution is suspended, and prompts for another command: 


DBG> SET BREAK COUNT 
DBG> GO 


break at routine PROG2\COUNT 
54: procedure COUNT (X, Y: INTEGER) ; 
DBG> 


SET TRACE Command Overview 


The SET TRACE command enables you to select program locations or 
events for tracing the execution of your program without stopping its 
execution (tracepoints). After setting a tracepoint, you can start execution 
with the GO command and then monitor that location, checking for 
unexpected behavior. By setting a tracepoint on a routine, you can also 
monitor the number of times it is called. 


The debugger’s default behavior at a tracepoint is identical to that at a 
breakpoint, except that program execution continues past a tracepoint. 
Thus, the DBG> prompt is not displayed when a tracepoint is reached and 
announced by the debugger. 


Except for the command name, the syntax of the SET TRACE command is 
identical to that of the SET BREAK command: 


SET TRACE[/qualifier[, ... ]] [address-expression[, ... ]] 
[WHEN (conditional-expression)] 
[DO (command[;... ])] 


The SET TRACE and SET BREAK commands have the same qualifiers. 
When using the SET TRACE command, you specify address expressions, 
qualifiers, and the optional WHEN and DO clauses exactly as with the 
SET BREAK command. 


Unless you use the /TEMPORARY qualifier on the SET BREAK (or SET 
TRACE) command, breakpoints (and tracepoints) remain in effect until 
you cancel them or exit the debugging session. 
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To identify all of the breakpoints (or tracepoints) that are currently set, use 
the SHOW BREAK (or SHOW TRACE) command. To cancel breakpoints 
(or tracepoints), use the CANCEL BREAK (or CANCEL TRACE) command 
(see Section 3.5.6). 


The following sections describe how to specify program locations and 
events with the SET BREAK and SET TRACE commands. 


3.5.1. Setting Breakpoints or Tracepoints on Individual Program Locations 


To set a breakpoint (or a tracepoint) on a particular program location, 
specify an address expression with the SET BREAK (or SET TRACE) 
command. 


Fundamentally, an address expression specifies a memory address or a 
VAX register. Because the debugger understands the symbols associated 
with your program, the address expressions you typically use with the SET 
BREAK (or SET TRACE) command are routine names, labels, or source 
line numbers rather than memory addresses—the debugger converts these 
symbols to addresses. 


3.5.1.1 Specifying Symbolic Addresses 
Note: In some cases, when using the SET BREAK or SET TRACE 
command with a symbolic address expression, you might need 
to set a module or specify a scope or a path name. Those concepts 
are described in detail in Chapter 5. The examples in this section 
assume that all modules are set and that all symbols referenced 
are uniquely defined, unless otherwise indicated. 


The following examples illustrate how to set a breakpoint (or a tracepoint) 
on a routine (SWAP) and a label (LOOP1): 


DBG> SET BREAK SWAP 
DBG> SET TRACE LOOP1 


The next command sets a breakpoint on the RET (return) instruction of 
routine SWAP. "Breaking" on the RET instruction of a routine enables you 
to inspect the local environment before the RET instruction removes the 
routine’s call frame from the call stack. 


DBG> SET BREAK/RETURN SWAP 


Some languages, for example FORTRAN, use numeric labels. To set a 
breakpoint (or a tracepoint) on a numeric label, you must precede the 
number with the built-in symbol @LABEL. Otherwise, the debugger 
interprets the number as a memory address. For example, the following 
command sets a tracepoint on label 20. 


DBG> SET TRACE SLABEL 20 


You can set a breakpoint (or a tracepoint) on a line of source code by 
specifying the line number preceded by the built-in symbol 2LINE. The 
following command sets a breakpoint on line 14. 


DBG> SET BREAK %SLINE 14 
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The preceding breakpoint causes execution to be suspended when the 

PC value is on the first instruction of line 14. Note that you can set a 
breakpoint (or a tracepoint) only on lines for which the compiler generated 
instructions (lines that resulted in executable code). If you specify a line 
number that is not associated with an instruction, such as a comment 
line or a statement that declares but does not initialize a variable, the 
debugger issues a diagnostic message. For example: 


DBG> SET BREAK %SLINE 6 

SDEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 
SDEBUG-E-NOSYMBOL, symbol ‘%LINE 6’ is not in the symbol table 
DBG> 


The preceding messages indicate that the compiler did not generate 
instructions for lines 6 or 7 in this case. 


Some languages, for example BASIC, allow more than one statement on 

a line. In such cases, you can use statement numbers to differentiate 
among statements on the same line. A statement number consists of a line 
number, followed by a period (.) and a number indicating the statement. 
The format is as follows: 


SLINE line-number.statement-number 


For example, the following command sets a tracepoint on the second 
statement of line 38: 


DBG> SET TRACE %LINE 38.2 


When searching for symbols that you reference in commands, the debugger 
uses the conventions described in Section 5.3.1. That is, it first looks 
within the module where execution is currently suspended, then in other 
scopes associated with routines on the call stack, and so on. Therefore, to 
specify a symbol that is defined in more than one module, such as a line 
number, you might need to use a path name. For example, the following 
command sets a tracepoint on line 27 of module MOD4: 


DBG> SET TRACE MOD4\S$LINE 27 


Remember the symbol lookup conventions when specifying a line number 
in debugger commands. If that line number is not defined in the module 
where execution is suspended (because it is not associated with an 
instruction), the debugger uses the symbol lookup conventions to locate 
another module where the line number is defined. 


When specifying address expressions, you can combine symbolic addresses 
with byte offsets. Thus, you can set a breakpoint (or a tracepoint) on a 
particular assembly language instruction by specifying its line number 
and the byte offset from the beginning of that line to the first byte of the 
instruction. For example, the next command sets a breakpoint on the 
address that is five bytes beyond the beginning of line 23. 


DBG> SET BREAK *sLINE 23+5 
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3.5.1.2 Specifying Locations in Memory 
To set a breakpoint (or a tracepoint) on a location in memory, specify its 
numerical address in the currently set radix The default radix for both 
data entry and display is decimal for all languages except BLISS and 
MACRO. It is hexadecimal for BLISS and MACRO. For example, the 
following command sets a breakpoint at address 2753, decimal (for all 
languages except BLISS or MACRO), or at address 27753, hexadecimal (for 
BLISS and MACRO): 


DBG> SET BREAK 2753 


You can specify a radix when you enter an individual integer literal (such 
as 2753) by using one of the built-in symbols BIN, %OCT, %DEC, or 
%HEX. For example, in the following command line the symbol HEX 
specifies that 2753 should be treated as a hexadecimal integer: 


DBG> SET BREAK %SHEX 2753 


Note that when specifying a hexadecimal number that starts with a 
letter rather than a number, you must add a leading "0". Otherwise, the 
debugger tries to interpret the entity specified as a symbol declared in 
your program. 


See Section 4.1.9 and Appendix D for additional information about 
specifying radixes and on the built-in symbols BIN, %DEC, %HEX, 
and %OCT. 


If a breakpoint (or a tracepoint) was set on a numerical address that 
corresponds to a symbol in your program, the SHOW BREAK (or SHOW 
TRACE) command identifies the breakpoint symbolically. 


3.5.1.3. Obtaining and Symbolizing Memory Addresses 
Use the EVALUATE/ADDRESS command to determine the memory 
address associated with a symbolic address expression, such as a line 
number, routine name, or label. For example: 


DBG> EVALUATE/ADDRESS SWAP 
1536 

DBG> EVALUATE/ADDRESS %SLINE 26 
1629 

DBG> 


The address is displayed in the current radix. You can specify a radix 
qualifier to display the address in another radix. For example: 


DBG> EVALUATE/ADDRESS/HEX SLINE 26 
OO000065D 
DBG> 


The command SYMBOLIZE does the reverse of EVALUATE/ADDRESS. It 
converts a memory address into its symbolic representation (including its 
path name) if such a representation is possible. Chapter 5 explains how 
to control symbolization. See Section 4.1.10 for more information about 
obtaining and symbolizing addresses. 
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3.5.2 Setting Breakpoints or Tracepoints on Lines or Instructions 


Several SET BREAK (and SET TRACE) command qualifiers cause the 
debugger to break on (or trace) every source line or every assembly 
language instruction of a particular class: 


/LINE 

/BRANCH 

/CALL 

JAINSTRUCTION 
/INSTRUCTION=(opcodel, . . . J) 


When using these qualifiers, do not specify an address expression. 


For example, the following command causes the debugger to break on the 
beginning of every source line encountered during execution: 


DBG> SET BREAK/LINE 


The instruction-related qualifiers are especially useful for opcode tracing, 
which is the tracing of all instructions or the tracing of a class of 
instructions. The next command causes the debugger to trace every 
branch instruction encountered (for example BEQL, BGTR, and so on): 


DBG> SET TRACE/BRANCH 
Note that opcode tracing slows program execution, 


By default, when you use the qualifiers discussed in this section, the 
debugger breaks (or traces) within all called routines as well as within the 
currently executing routine (this is equivalent to specifying SET BREAK 
/JINTO or SET TRACEANTO). By specifying SET BREAK/OVER or SET 
TRACE/OVER, you can suppress break (or trace) action within all called 
routines. Or, you can use the /[NO]JSB, [NO]JSHARE, or /[NO|JSYSTEM 
qualifiers to specify the kinds of called routines where break (or trace) 
action is to be suppressed. For example, the next command causes the 
debugger to break on every line except within called routines that are in 
shareable images or system space: 


DBG> SET BREAK/LINE/NOSHARE/NOSYSTEM 


3.5.3 Controlling Debugger Action at Breakpoints or Tracepoints 


The SET BREAK and SET TRACE commands provide several options for 
controlling the behavior of the debugger at breakpoints and tracepoints— 
the /AFTER, /[NO]SILENT, /[NO]JSOURCE, and /TEMPORARY command 
qualifiers, and the optional WHEN and DO clauses. The following 
examples illustrate several of these options. 


The next command sets a breakpoint on line 14 and specifies that the 
breakpoint take effect after the fifth time that line 14 is executed: 


DBG> SET BREAK/AFTER:5 SLINE 14 
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The next command sets a tracepoint that is triggered at every line of 
execution. The DO clause obtains the value of the variable X when each 
line is executed: 


DBG> SET TRACE/LINE DO (EXAMINE X) 


The next example illustrates how the WHEN and DO clauses can be used 
together. The command sets a breakpoint at line 27. The breakpoint is 
triggered (execution is suspended) only when the value of SUM is greater 
than 100 (not each time line 27 is executed). The DO clause causes the 
value of TEST_RESULT to be examined whenever the breakpoint is 
triggered—that is, whenever the value of SUM is greater than 100. If the 
value of SUM is not greater than 100 when execution reaches line 27, the 
breakpoint is not triggered and the DO clause is not executed. 


DBG> SET BREAK sLINE 27 WHEN (SUM > 100) DO (EXAMINE TEST RESULT) 


See Section 4.1.5 and Section 9.3.2.2 for information about evaluating 
language expressions, such as the expression "SUM >100". 


The /SILENT qualifier suppresses the break or trace message and source 
code display. This is useful when, for example, you want to use the SET 
TRACE command only to execute a debugger command at the tracepoint. 
In the next example, the SET TRACE command is used to examine the 
value of the Boolean variable STATUS at the tracepoint. 


DBG> SET TRACE/SILENT %LINE 83 DO (EXAMINE STATUS) 
DBG> GO 


SCREEN_IO\CLEAR\STATUS: OFF 


In the next example, the SET TRACE command is used to count the 
number of times line 12 is executed. The first DEFINE/VALUE command 
defines a symbol COUNT and initializes its value to zero. The DO 

clause of the SET TRACE command causes the value of COUNT to be 
incremented and evaluated whenever the tracepoint is triggered (whenever 
execution reaches line 12). 


DBG> DEFINE/VALUE COUNT=0 
DBG> SET TRACE/SILENT SLINE 12 DO (DEF/VAL COUNT=COUNT+1;EVAL COUNT) 


Source lines are displayed by default at breakpoints, tracepoints, and 
watchpoints if they are available for the module being debugged. You can 
also control their display with the SET STEP [NOJSOURCE command and 
the (NOJSOURCE qualifier of the SET BREAK, SET TRACE, and SET 
WATCH commands. See Chapter 6 for information about how to control 
the display of source code in general and in particular at breakpoints, 
tracepoints, and watchpoints. 
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Setting Breakpoints or Tracepoints on Exceptions 


The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands 
direct the debugger to treat any exception generated by your program as 
a breakpoint or tracepoint, respectively. The breakpoint (or tracepoint) 
occurs before any application-declared exception handler is invoked. See 
Section 9.4 for debugging techniques associated with exceptions and 
condition handlers. 


Setting Breakpoints or Tracepoints on Language-Specific Events 
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Note: 


The SET BREAK and SET TRACE commands each have an 
/EVENT=event-name qualifier. You can use this qualifier to set 
breakpoints or tracepoints to be triggered by various language-specific 
events (denoted by event-name keywords). 


Currently, event-name keywords are defined only for Ada and 
SCAN. See the VAX Ada and VAX SCAN documentation for 
complete information. 


When you run a program under debugger control, the appropriate set 

of event-name keywords is defined during the initialization of language- 
specific parameters. Use the SHOW EVENT_FACILITY command to 
identify the event-name keywords that apply to the current language. The 
SET EVENT_FACILITY command enables you to initialize the debugger 
for events that are specific to another language. 


The following examples briefly illustrate how to set event breakpoints 
with Ada tasking programs and SCAN programs. When a breakpoint or 
tracepoint is triggered, the debugger identifies the event that caused it to 
be triggered and gives additional information. 


The following command causes the debugger to break whenever any Ada 
task enters the TERMINATED state. 


DBG> SET BREAK/EVENT=TERMINATED 


The next command sets two tracepoints, which are associated with the Ada 
tasks CHECKIN and RESERVE, respectively. Each tracepoint is triggered 
whenever its associated task makes a transition to the RUN state. 


DBG> SET TRACE/EVENT=RUN CHECKIN, RESERVE 


The next command causes the debugger to break whenever a SCAN token 
is built, for any value. 


DBG> SET BREAK/EVENT=TOKEN 


See Section 9.3.2 for inforraation about predefined Ada event breakpoints. 
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3.5.6 Canceling Breakpoints or Tracepoints 


Use the CANCEL BREAK and CANCEL TRACE commands to cancel 
breakpoints and tracepoints, respectively. To cancel a breakpoint (or a 
tracepoint), specify address expressions and qualifiers exactly as you 
specified them when setting the breakpoint (or tracepoint). 


Thus, to cancel breakpoints (or tracepoints) that were set at specific 
address expressions, specify those same address expressions. For example: 


DBG> CANCEL BREAK SWAP,MOD2\LOOP4, 2753 


To cancel breakpoints (or tracepoints) that were set with the following 
command qualifiers, specify those same command qualifiers: /BRANCH, 
/CALL, /EVENT=event-name, /EXCEPTION, /AINSTRUCTION, 
JINSTRUCTION=(opcode[, ... ]), /LINE. If the qualifier requires one 

or more keywords, include the keywords associated with the breakpoints 
or tracepoints to be canceled. For example: 


DBG> CANCEL BREAK/LINE 
DBG> CANCEL TRACE/INSTRUCTION=(JSB, CALLS) 
DBG> CANCEL TRACE/EVENT=RUN CHECKIN 


3.6 Monitoring Changes in Variables and Other Program Locations 


Note: 


The SET WATCH command enables you to specify program variables (or 
arbitrary memory locations) that the debugger monitors as your program 
executes. This process is called setting watchpoints. If, during execution, 
the program modifies the value of a "watched" variable (or memory 
location), the watchpoint is triggered. The debugger then suspends 
execution, displays information, and prompts for more commands. The 
debugger monitors watchpoints continuously during program execution. 


This section describes the general use of the SET WATCH command. 
Section 3.6.2 gives additional information pertaining to setting 
watchpoints on nonstatic variables—variables that are allocated on the 
call stack or in registers. 


In some cases, when using the SET WATCH command with a 
variable name (or any other symbolic address expression) you 
might need to set a module or specify a scope or a path name. 
Those concepts are described in Chapter 5. The examples in this 
section assume that all modules are set and that all variable names 
are uniquely defined. 


If your program was optimized during compilation, certain 
variables in the program might be removed by the compiler. If 


you then try to set a watchpoint on such a variable, the debugger 
issues a warning (see Section 9.1). 


The syntax of the SET WATCH command is as follows: 


SET WATCH{/qualifier[, ... ]] [address-expression[, ...  ]] 
[WHEN (conditional-expression)] 
[DO (command[;... ])] 
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Although any valid address expression can be specified, usually you specify 
the name of a variable. The example that follows shows a typical use of 
the SET WATCH command and illustrates the general default behavior of 
the debugger at a watchpoint. 


DBG> SET WATCH COUNT 
DBG> GO 


watch of MOD2\COUNT at MOD2\%LINE 24 
24; COUNT := COUNT + 1; 
old value: 27 
new value: 28 
break at MOD2\%LINE 25 
25% END; 
DBG> 


In this example, the SET WATCH command sets a watchpoint on the 
variable COUNT, and the GO command starts execution. When the 
program changes the value of COUNT, execution is suspended. The 
debugger then does the following: 


e Announces the event ("watch of MOD2\COUNT ... "), identifying 
the location of the instruction that changed the value of the watched 
variable ("... at MOD2\ LINE 24") 


e Displays the associated source line (24) 
e Displays the old and new values of the variable (27 and 28) 


e Announces that execution has been suspended at the beginning of the 
next line ("break at MOD2\ @LINE 25") and displays that source line 


¢ Prompts for another command 


When the address of the instruction that modified a watched variable is 
not at the beginning of a source line, the debugger denotes the instruction’s 
location by displaying the line number plus the byte offset from the 
beginning of the line. For example: 


DBG> SET WATCH K 
DBG> GO 


watch of TEST\K at TEST\SLINE 19+5 
19; DO 40 K= 1, J 
old value: 4 
new value: 5 
break at TEST\SLINE 19+9 
19; DO 40 K= 1, J 
DBG> 


In this example, the address of the instruction that modified variable K is 
5 bytes beyond the beginning of line 19. Note that the breakpoint is on the 
instruction that follows the instruction that modified the variable (not on 
the beginning of the next source line as in the preceding example). 
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You can set watchpoints on aggregates (that is, entire arrays or records). 
A watchpoint set on an array or record triggers if any element of the array 
or record changes. Thus, you do not need to set watchpoints on individual 
array elements or record components. Note, however, that you cannot set 
an aggregate watchpoint on a variant record. In the following example, 
the watchpoint is triggered because element 3 of array ARR was modified: 


DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBR\SLINE 12 


12: ARR(3) := 28 
old value: 

i ee 7 

(2) LZ 

(3): 3 

(4): 0 
new value: 

(1): 7 

(2): 12 

(3): 28 

(4): 0 


break at SUBR\%LINE 13 
DBG> 


You can also set a watchpoint on a record component, on an individual 
array element, or on an array slice (a range of array elements). A 
watchpoint set on an array slice triggers if any element within that 

slice changes. When setting the watchpoint, use the syntax of the current 
language. For example, the following command sets a watchpoint on 
element 7 of array CHECK using Pascal syntax: 


DBG> SET WATCH CHECK [7] 


To identify all of the watchpoints that are currently set, use the SHOW 
WATCH command. To cancel watchpoints, use the CANCEL WATCH 
command. 


Note that the SET BREAK/MODIFY command has the same effect as the 
SET WATCH command. 


3.6.1. Watchpoint Options 


The SET WATCH command provides the same options for controlling the 
behavior of the debugger at watchpoints that the SET BREAK and SET 
TRACE commands provide for breakpoints and tracepoints—namely the 
/AFTER, /[LNOJSILENT, /INOJSOURCE, and /TEMPORARY command 
qualifiers, and the optional WHEN and DO clauses. See Section 3.5.3 for 
examples. 
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3.6.2 Watching Nonstatic Variables 


DBG> SET WATCH Y 


Storage for a variable in your program is allocated either statically or 
nonstatically. A static variable is associated with the same memory 
address throughout execution of the program. A nonstatic variable is 
allocated on the call stack or in a register and has a value only when its 
defining routine is active, on the call stack. As explained in this section, 
the technique for setting a watchpoint, the watchpoint’s behavior, and the 
speed of program execution are different for the two kinds of variables. 


To determine how a variable is allocated, use the EVALUATE/ADDRESS 
command. A static variable generally has its address in PO space (0 to 
3FFFFFFF, hexadecimal). A nonstatic variable generally has its address 
in P1 space (40000000 to 7FFFFFFF, hexadecimal) or is in a register. 
In the following Pascal code example, X is declared as a static variable, 
whereas Y is a nonstatic variable (by default). The EVALUATE/ADDRESS 
command, entered while debugging, shows that X is allocated at memory 
location 512, whereas Y is allocated in register RO: 
VAR 

X: [STATIC] INTEGER; 

Y: INTEGER; 


DBG> EVALUATE/ADDRESS X 
O12 
DBG> EVALUATE/ADDRESS Y 
SRO 
DBG> 


When using the SET WATCH command, note the following distinction. 
You can set a watchpoint on a static variable regardless of the PC value 
when you enter the command; but you can set a watchpoint on a nonstatic 
variable only when the PC value is within the routine where that variable 
is defined. Otherwise, the debugger issues a warning. For example: 


SDEBUG-W-SYMNOTACT, nonstatic variable ‘’MOD4\ROUT3\Y’ is not active 


DBG> 
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Section 3.6.2.2 describes how to set a watchpoint on a nonstatic variable. 


Execution Speed 


When a watchpoint is set, the speed of program execution depends on 
whether the variable is static or nonstatic. To watch a static variable, 

the debugger write-protects the page containing the variable. [If your 
program attempts to write to that page (modify the value of that variable), 
an access violation occurs and the debugger handles the exception. The 
debugger temporarily unprotects the page to allow the instruction to 
complete and then determines whether the watched variable was modified. 
Except when writing to that page, the program executes at full speed. 


Because problems arise if the call stack or registers are write-protected, 
the debugger must use another technique to watch a nonstatic variable. It 
traces every instruction in the variable’s defining routine and checks the 
value of the variable after each instruction has been executed. Because 
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this significantly slows down the execution of the program, the debugger 
issues the following message when you set a nonstatic watchpoint: 


DBG> SET WATCH Y 


S$DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 
DBG> 


3.6.2.2 Setting a Watchpoint on a Nonstatic Variable 
To set a watchpoint on a nonstatic variable, make sure that the PC value is 
within the defining routine. A convenient technique is to set a tracepoint 
on that routine, also specifying a DO clause to set the watchpoint. 
Thus, whenever the routine is called, the tracepoint is triggered and 
the watchpoint is automatically set on the local variable. In the following 
example, the WPTTRACE message indicates that a watchpoint has been 
set on Y, a nonstatic variable that is local to routine ROUTS: 


DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y) 
DBG> GO 


trace at routine MOD4\ROUT3 
SDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\%SLINE 16 


16: Y := 4 
old value: S 
new value: 4 
break at MOD4\ROUT3\%SLINE 17 
dB a SWAP (X,Y); 
DBG> 


When execution returns to the caller of routine ROUTS, variable Y is 
no longer active. Therefore, the debugger automatically cancels the 
watchpoint and issues the following messages: 


SDEBUG-I-WATCHVAR, watched variable MOD4\ROUT3\Y has gone out of scope 
SDEBUG-I-WATCHCAN, watchpoint now cancelled 


3.6.2.3. Options for Watching Nonstatic Variables 
The SET WATCH command qualifiers /OVER, /INTO, and /[NOJSTATIC 
provide options for watching nonstatic variables. 


When you set a watchpoint on a nonstatic variable, you can direct the 
debugger to do one of two things at a routine call: 


e Step over the called routine—executing it at full speed—and resume 
instruction tracing after returning. This is the default (SET WATCH 
/OVER). 


e Trace instructions within the called routine, thereby monitoring the 
variable instruction-by-instruction within the routine (SET WATCH 
INTO). 
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Using the SET WATCH/OVER command results in better performance. 
But it also means that, if the called routine modifies the watched variable, 
the watchpoint is triggered only after execution returns from that routine. 
The SET WATCH/INTO command slows down program execution but 
enables you to monitor watchpoints more precisely within called routines. 


The debugger determines whether a variable is static or nonstatic by 
looking at its address (PO space, P1 space, or register). When entering 

a SET WATCH command, you can override this decision with the 
/[NOJSTATIC qualifier. For example, if you have allocated nonstack 
storage in Pl space, use the SET WATCH/STATIC command to specify that 
a particular variable is static even though it is in Pl space. Conversely, if 
you have allocated your own call stack in PO space, use the SET WATCH 
/NOSTATIC command to specify that a particular variable is nonstatic 
even though it is in PO space. 


3.6.2.4 Setting Watchpoints in Installed Writeable Shareable Images 


When setting a watchpoint in an installed writeable shareable image, use 
the command SET WATCH/NOSTATIC (see Section 3.6.2.3). 


The reason you must set a nonstatic watchpoint is as follows. Variables 
declared in such shareable images are typically static variables. By 
default, the debugger watches a static variable by write-protecting the 
page containing that variable. However, the debugger cannot write- 
protect a page in an installed writeable shareable image. Therefore, 

the debugger must use the slower method of detecting changes, as for 
nonstatic variables—that is, by checking the value at the watched location 
after each instruction has been executed (see Section 3.6.2.1). 


Note that if any other process modifies the watched location’s value, the 
debugger may report that your program modified the watched location. 


3.f How the Debugger Controls Program Execution 
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This section is for readers who are interested in how the debugger 
functions. 


The debugger controls and monitors execution by causing exceptions to 
occur at points of interest in your program. For example, it might put 

a breakpoint fault instruction (BPT) in your code, causing a breakpoint 
exception to occur when that instruction is executed. The debugger might 
also set the trace enable bit (T bit) in the processor status longword (PSL), 
thus causing a trace trap at the end of each instruction. 


When you run your program with the debugger, the debugger is the 
primary exception handler. Any exception resulting from the execution 

of your program, whether or not it is caused by the debugger, is first 
handled by the debugger. If the debugger did not cause the exception, it 
resignals the exception (refer to Section 9.4 for information and debugging 
techniques related to exceptions and condition handlers). If the debugger 
caused the exception, it takes appropriate action. For example, in the case 
of a tracepoint the debugger identifies the tracepoint and returns control to 
the program. In the case of a breakpoint, the debugger maintains control 
by identifying the breakpoint and then prompting for commands. 
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The following paragraphs illustrate the functioning of the debugger with 
some typical commands—-SET BREAK and STEP. See also Section 3.6.2 
and Section 9.4 for implementation information about the SET WATCH 

and SET BREAK/EXCEPTION commands, respectively. 


When you set a breakpoint, specifying a particular address expression, the 
debugger removes the opcode at that address and replaces it with the BPT 
instruction. When execution reaches that address, the BPT instruction 
causes a breakpoint fault, which gives control to the debugger: 


1 The debugger announces the breakpoint and prompts for commands. 
When you resume execution, the debugger performs the following 
steps. 


2 The debugger replaces the original opcode and sets the T bit of the 
saved PSL on the call stack, so that a trace trap occurs when the 
current instruction is executed. 


The instruction is executed. 


When the trace trap occurs, the debugger replaces the BPT instruction 
at the original breakpoint address, so that the break fault occurs 
whenever execution again reaches that address. 


When you enter a STEP/AINSTRUCTION command, the debugger sets the 
T bit of the saved PSL, executes the next instruction, then, when the trace 
trap occurs, issues a message and prompts for commands. 


The STEP/LINE command is implemented similarly, except that the 
debugger keeps track of line boundaries by correlating the low and high 
PC values of each line with data stored in the symbol table. The debugger 
completes the step and prompts for commands when you leave.the current 
line. 


When you set a breakpoint on a class of instructions and then start 
execution, the debugger traces (traps on) every instruction by setting the 
T bit of the saved PSL. If the next instruction is of the desired class, 
the debugger suspends execution on that instruction, announces the 
breakpoint, and prompts for commands. If the instruction is not of the 
desired class, the debugger continues to trace and execute instructions. 


When you enter a STEP/OVER command at a routine call, the debugger 
does the following: 


1 Steps into the routine, then sets a reserved bit in the saved PSL. 


2 Lets the program run. The routine is executed, but the RET 
instruction causes a reserved-operand exception when it tries to 
restore the modified PSL. 


3 Lets the RET instruction complete but sets the T bit to suspend 
execution after the RET instruction (in the calling routine) on the 
instruction that follows the original call. 


STEP/RETURN is also implemented by setting a reserved bit in the saved 
PSL. 
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Because the debugger and your program share the same address 

space, in some rare cases they can interfere with each other, causing 
unexpected behavior. The following paragraphs highlight possible sources 
of interference. 


Effect of Debugger on Uninitialized Variables 


Because the debugger acts as an exception handler, it uses the call - 
stack. This can cause uninitialized variables saved on the call stack to 
be modified by the debugger. 


If your program references an uninitialized variable that is in this state, 
the execution of the program can be affected. 


Effect of Debugger on Memory Usage 


Another source of possible interference between the debugger and your 
program is that they share memory. If your program is sensitive to 
changes in memory usage, the execution of the program can be affected. 


4 ~~ Examining and Manipulating Program Data 


This chapter explains how to use the EXAMINE and DEPOSIT commands 
to display and modify the values of symbols declared in your program 

as well as the contents of arbitrary program locations. The chapter also 
explains how to use the EVALUATE and other commands that evaluate 
language expressions. 


The topics covered in this chapter are organized as follows: 


e General concepts related to using the EXAMINE, DEPOSIT, and 
EVALUATE commands. 


e Use of the commands with symbolic names—for example, the names 
of variables and routines declared in your program. Such symbolic 
address expressions are associated with compiler generated types. 


e Use of the commands with program locations (memory addresses or 
registers) that do not have symbolic names. Such address expressions 
are not associated with compiler generated types. 


e Specifying a type to override the type associated with an address 
expression. 


The examples in this chapter do not cover all language-dependent 
behavior. When debugging in any language, be sure to consult the 
documentation supplied with that language. The chapter devoted to 
debugging in the user’s guide contains all language-dependent information 
for that language. The following sections of this manual also contain 
language-related information: 


e Appendix E tabulates the constructs and operators that are supported 
by the debugger for each language. 


e Section 9.3 highlights some important differences between languages 
that you should be aware of when debugging multilanguage programs. 





4.1 General Concepts 


This section introduces the EXAMINE, DEPOSIT, and EVALUATE 
commands and discusses concepts that are common to those commands. 


4.1.1. Accessing Variables While Debugging 


Before you try to examine or deposit into a nonstatic (stack-local or 
register) variable, its defining routine must be active—that is, on the 
call stack. That is, program execution must be suspended somewhere 
within the defining routine. See Section 3.6.2 for more information about 
nonstatic variables. 
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You can examine a static variable at any time during program execution, 
and you can examine a nonstatic variable as soon as execution reaches its 
defining routine. However, before you examine any variable, you should 
step or otherwise execute the program beyond the point where the variable 
is declared and initialized. The value contained in any uninitialized 
variable should be considered invalid. 


Many compilers optimize code to make the program run faster. If the 
code that you are debugging has been optimized, some program locations 
might not match what you would expect from looking at the source code. 
In particular, some optimization techniques eliminate certain variables, so 
that you no longer have access to them while debugging. 


Section 9.1 explains the effect of several optimization techniques on the 
executable code. When first debugging a program, it is best to disable 
optimization, if possible, with the /NOOPTIMIZE (or equivalent) compiler 
command qualifier. 


Note that, in some cases, when using the EXAMINE or DEPOSIT 
command with a variable name (or any other symbolic address expression) 
you might need to set a module or specify a scope or a path name. Those 
concepts are described in Chapter 5. The examples in this chapter assume 
that all modules are set and that all variable names are uniquely defined. 


4.1.2 Using the EXAMINE Command 
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For high-level language programs, the EXAMINE command is used mostly 
to display the current value of variables, and it has the following form: 


EXAMINE variable-name[,... ] 


Thus, for example, the following command displays the current value of 
the integer variable X: 


DBG> EXAMINE X 
MOD3\X: 17 
DBG> 


When displaying the value, the debugger prefixes the variable name with 
its path name—in this case, the name of the module where variable X is 
declared (see Section 5.3.2). 


More generally, the EXAMINE command displays the current value of the 
entity denoted by an address expression, in the type associated with that 
location (for example, integer, real, array, record, and so on). The basic 
format of the EXAMINE command is as follows: 


EXAMINE address-expression[,... ] 


When you enter an EXAMINE command, the debugger evaluates the 
address expression to yield a program location (a memory address or a 
register). The debugger then displays the value stored at that location as 
follows: 


e Ifthe location has a symbolic name, the debugger formats the value 
according to the compiler generated type associated with that symbol. 
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e Ifthe location does not have a symbolic name, the debugger formats 
the value in the type longword integer by default. 


See Section 4.1.4 for more information about the types associated with 
symbolic and nonsymbolic address expressions. 


By default, when displaying the value, the debugger identifies the 
address expression and its path name symbolically if symbol information 
is available. See Section 4.1.10 for additional information about 
symbolization of addresses. 


4.1.3. Using the DEPOSIT Command 


For high-level languages, the DEPOSIT command is used mostly to assign 
a new value to a variable. The command is like an assignment statement 
in most programming languages, and it has the following form: 


DEPOSIT variable-name = value 


Thus, for example, the following DEPOSIT command assigns the value 23 
to the integer variable X: 


DBG> EXAMINE X 
MOD3\X: 17 

DBG> DEPOSIT X = 23 
DBG> EXAMINE X 
MOD3\X: 23 

DBG> 


More generally, the DEPOSIT command evaluates a language expression 
and deposits the resulting value into a program location denoted by an 
address expression. The basic format of the DEPOSIT command is as 
follows: 


DEPOSIT address-expression = language-expression 
When you enter a DEPOSIT command, the debugger does the following: 
e It evaluates the address expression to yield a program location. 


e Ifthe program location has a symbolic name, the debugger associates 
the location with the symbol’s compiler generated type. If the location 
does not have a symbolic name, the debugger associates the location 
with the type longword integer, by default (see Section 4.1.4). ~ 


e It evaluates the language expression in the syntax of the current 
language and in the current radix to yield a value. This behavior is 
identical to that of the EVALUATE command (see Section 4.1.5). 


e It checks that the value and type of the language expression is 
consistent with the type of the address expression. If you try to 
deposit a value that is incompatible with the type of the address 
expression, the debugger issues a diagnostic message. If the value is 
compatible, the debugger deposits the value into the location denoted 
by the address expression. 
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Note that the debugger might do type conversion during a deposit 
operation if the language rules allow it. For example, assume X is an 
integer variable. In the following example, the real value 2.0 is converted 
to the integer value 2, which is then assigned to X: 


DBG> DEPOSIT X = 2.0 
DBG> EXAMINE X 
MOD3\X: 2 

DBG> 


In general, the debugger tries to follow the assignment rules for the 
current language. 


4.1.4 Address Expressions and Their Associated Types 


The symbols that are declared in your program (variable names, routine 
names, and so on) are symbolic address expressions. They denote memory 
addresses or registers. Symbolic address expressions (also called symbolic 
names in this chapter) have compiler generated types, and the debugger 
knows the type and location that are associated with symbolic names. 
Section 4.1.10 explains how to obtain memory addresses and register 
names from symbolic names and how to symbolize program locations. 


Symbolic names include the following categories: 


e Variables. The associated program locations contain the current values 
of variables. Techniques for examining and depositing into variables 
are described in Section 4.2. 


© Routines, labels, and line numbers. The associated program 
locations contain VAX assembly-language instructions. Techniques 
for examining and depositing VAX instructions are described in 
Section 4.3. 


Program locations that do not have a symbolic name are not associated 
with a compiler generated type. To enable you to examine and deposit 
into such locations, the debugger associates them with the default type 
longword integer. This means that, if you specify a location that does not 
have a symbolic name, the EXAMINE command displays the contents 

of 4 bytes starting at the address specified and formats the displayed 
information as an integer value. In the following example, the memory 
address 926 is not associated with a symbolic name (note that the address 
is not symbolized when the EXAMINE command is executed). Therefore, 
the EXAMINE command displays the value at that address as a longword 
integer: 


DBG> EXAMINE 926 
926: 749404624 
DBG> 


Similarly, by default you can deposit up to 4 bytes of integer data into a 
program location that does not have a symbolic name. And this data is 
formatted as a longword integer. For example: 


DBG> DEPOSIT 926 = 84 
DBG> EXAMINE 926 

926: 84 

DBG> 
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Techniques for examining and depositing into locations that do not have a 
symbolic name are described in Section 4.5. 


The EXAMINE and DEPOSIT commands accept type qualifiers (/ASCII:n, 
/BYTE, and so on) that enable you to override the type associated with a 
program location. This is useful if you want the contents of the location 
to be interpreted and displayed in another type, or if you want to deposit 
some value of a particular type into a location that is associated with 
another type. Techniques for overriding a type are described in Section 4.5. 


4.1.5 Evaluating Language Expressions 


A language expression consists of any combination of one or more 
symbols, literals, and operators that is evaluated to a single value 

in the syntax of the current language and in the current radix. (The 
current language and current radix are defined in Section 4.1.8 and 
Section 4.1.9, respectively.) Several debugger commands and constructs 
evaluate language expressions: 


e The EVALUATE and DEPOSIT commands, which are described in this 
section and in Section 4.1.3, respectively. 


e The IF, FOR, REPEAT, and WHILE commands (see Section 8.6). 


¢ WHEN clauses, which are used with the SET BREAK, SET TRACE, 
and SET WATCH commands (see Section 3.5.3). 


Although this discussion applies to all commands and constructs that 
evaluate language expressions, it focuses on the use of the EVALUATE 
command. 


The EVALUATE command evaluates one or more language expressions in 
the syntax of the current language and in the current radix and displays 
the resulting values. The command has the following form: 


EVALUATE language-expression[,... ] 


One use of the EVALUATE command is as a calculator, to perform 
arithmetic calculations that might be unrelated to your program. For 
example: 

DBG> EVALUATE (8+12)*6/4 


30 
DBG> 


The debugger uses the rules of operator precedence of the current language 
when evaluating language expressions. 


You can also evaluate language expressions that include variables and 
other constructs. For example, the following EVALUATE command 
subtracts 3 from the current value of the integer variable X, multiplies 
the result by 4, and displays the resulting value: 


DBG> DEPOSIT X = 23 

DBG> EVALUATE (X - 3) * 4 
80 

DBG> 
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If an expression contains symbols with different compiler generated types, 
the debugger uses the type-conversion rules of the current language 

to evaluate the expression. If the types are incompatible, a diagnostic 
message is issued. Debugger support for operators and other constructs in 
language expressions is tabulated in Appendix E for each language. You 
can also obtain information by typing "HELP LANGUAGE 
language-name". 


The built-in symbol %CURVAL denotes the current value—the value last 
displayed by an EVALUATE or EXAMINE command, or deposited by a 
DEPOSIT command. The backslash (\ ) also denotes the current value 
when used in that context. For example: 


DBG> EXAMINE X 
MOD3\X: 23 

DBG> EVALUATE SCURVAL 
23 

DBG> DEPOSIT Y = 47 
DBG> EVALUATE \ 

47] 

DBG> 


Using Variables in Language Expressions 


You can use variables in language expressions in much the same way that 
you use them in the source code of your program. 


Thus, the debugger generally interprets a variable used in a language 
expression as the current value of that variable, not the address of the 
variable. For example (X is an integer variable): 


DBG> DEPOSIT X = 12 ! Assign the value 12 to X 
CBG> EXAMINE X Display the value of X 
MOD4\X: 12 

DBG> EVALUATE X 

12 

DBG> EVALUATE X + 4 
16 

DBG> DEPOSIT X = X/2 


Evaluate and display the value of X 


Add the value of X to 4 


Divide the value of X by 2 and assign 
! the resuiting value to X 

DBG> EXAMINE X Display the new value of X 

MOD4\X: 6 


DBG> 


Note that the use of a variable in a language expression as illustrated in 
the previous examples is generally limited to single-valued, noncomposite 
variables. Typically, you can specify a multi-valued, composite variable 
(like an array or record) in a language expression only if the syntax 
indicates that you are referencing only a single value (a single element of 
the aggregate). For example, if ARR is the name of an array of integers, 
the following command is invalid: 


DBG> EVALUATE ARR 


SDEBUG~W-NOVALUE, reference does not have a value 
DBG> 
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However, the following commands are valid because only a single element 
of the array is referenced: 


DBG> EVALUATE ARR(2) ! Evaluate element 2 of array ARR 
37 

DBG> DEPOSIT K = 5 + ARR(2) ! Deposit the sum of two integer 
DBG> ! values into an integer variable 


Note also that, if the current language is BLISS, the debugger interprets 
a variable in a language expression as the address of that variable. To 
denote the value stored in a variable, you must use the contents-of 
operator (period (.)). For example, when the language is set to BLISS: 


DBG> EXAMINE Y ! Display the value of Y. 
MOD4\Y: 3 

DBG> EVALUATE Y ! Display the address of Y. 
02475B 

DBG> EVALUATE .Y ! Display the value of Y. 

3 

DBG> EVALUATE Y + 4 ! Add 4 to the address of Y and 
02475F ! display the resulting value. 


! 
DBG> EVALUATE .Y + 4 ! Add 4 to the value of Y and display 
7 ! the resulting value. 

DBG> 


For all languages, to obtain the address of a variable, use the EVALUATE 
/ADDRESS command, as described in Section 4.1.10. The EVALUATE and 
EVALUATE/ADDRESS commands both display the address of an address 
expression when the language is set to BLISS. 


4.1.5.2 Numeric Type Conversion by the Debugger 
When evaluating language expressions involving numeric types of 
different precision, the debugger first converts lower-precision types to 
higher-precision types before performing the evaluation. In the following 
example, the debugger converts the integer 1 to the real 1.0 before doing 
the addition. 


DBG> EVALUATE 1.5 + 1 
260 
DBG> 


The basic rules are as follows. If integer and real types are mixed, the 
integer type is converted to the real type. If integer types of different sizes 
are mixed (for example, byte-integer and word-integer), the one with the 
smaller size is converted to the larger size. If real types of different sizes 
are mixed (for example, G_float and H_float), the one with the smaller size 
is converted to the larger size. 


In general, the debugger allows more numeric type conversion than 

the programming language. In addition, the hardware type used for a 
debugger calculation (word, longword; G_float, and so on) might differ 
from that chosen by the compiler. Because the debugger is not as strongly 
typed or as precise as some languages, the evaluation of an expression 
by the EVALUATE command might differ from the result that would be 
calculated by compiler generated code and obtained with the EXAMINE 
command. 
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4.1.6 Address Expressions Compared to Language Expressions 


Do not confuse address expressions with language expressions. An 
address expression specifies a program location, whereas a language 
expression specifies a value. In particular, the EXAMINE command 
expects an address expression as its parameter, and the EVALUATE 
command expects a language expression as its parameter. These points 
are illustrated in the next examples. 


In the following example, the value 12 is deposited into the variable X. 
This is confirmed by the EXAMINE command. The EVALUATE command 
computes and displays the sum of the current value of X and the integer 
literal 6: 


DBG> DEPOSIT X = 12 
DBG> EXAMINE X 


MOD3\X: 12 

DBG> EVALUATE X + 6 
18 

DBG> 


In the next example, the EXAMINE command displays the value currently 
stored at the memory location that is 6 bytes beyond the address of X. 


DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 


In this case the location is not associated with a compiler generated type. 
Therefore, the debugger interprets and displays the value stored at that 
location in the type longword integer (see Section 4.1.4). 


In the next example, the value of X + 6 (that is, 18) is deposited into the 
location that is 6 bytes beyond the address of X. This is confirmed by the 
last EXAMINE command. 


DBG> EXAMINE X 

MOD3\X: 12 

DBG> DEPOSIT X + 6 = X + 6 
DBG> EXAMINE X 

MOD3\X: 12 

DBG> EXAMINE X + 6 
MOD3\X+6: 18 

DBG> 


4.1.7 Specifying the Current, Previous, and Next Entity 
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When using the EXAMINE and DEPOSIT commands, you can use three 
special built-in symbols (address expressions) to refer quickly to the 
current, previous, and next data locations (logical entities). These are the 
period (.), the circumflex (“), and the Return key. 


The period (.), when used by itself with an EXAMINE or DEPOSIT 
command, denotes the current entity—that is, the program location most 
recently referenced by an EXAMINE or DEPOSIT command. For example: 
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DBG> EXAMINE X 
SIZENK? <7 

DBG> DEPOSIT . = 12 
DBG> EXAMINE . 
SIZE\X: 12 

DBG> 


The circumflex (“) and Return key denote, respectively, the previous and 
next logical data locations relative to the last EXAMINE or DEPOSIT 
command (the logical predecessor and successor, respectively). The 
circumflex and Return key are useful for referring to consecutive indexed 
components of an array. The following example illustrates the use of these 
operators with an array of integers, ARR: 


DBG> EXAMINE ARR(5) ! Examine element 5 of array ARR 
MAIN\ARR (5): 448670 

DBG> EXAMINE %* ! Examine the previous element (4) 
MAIN\ARR (4): 792802 

DBG> EXAMINE ! Examine the next element (5) 
MATIN\ARR(5): 448670 

DBG> EXAMINE ! Examine the next element (6) 
MAIN\ARR (6): 891236 

DBG> 


The debugger uses the type associated with the current entity to determine 
logical successors and predecessors. 


You can also use the built-in symbols #%CURLOC, %PREVLOC, and 
%NEXTLOC to achieve the same purpose as the period, circumflex, and 
Return key, respectively. These symbols are useful in command procedures 
and also if your program uses the circumflex for other purposes. Moreover, 
using the Return key to signify the logical successor does not apply to all 
contexts. For example, you cannot press the Return key after typing the 
command DEPOSIT to indicate the next location, whereas you can always 
use the symbol %NEXTLOC for that purpose. 


Note that, like EXAMINE and DEPOSIT, the command EVALUATE 
/ADDRESS also resets the values of the current, previous, and next 
logical-entity built-in symbols (see Section 4.1.10). However, you cannot 
press the Return key after typing the command EVALUATE/ADDRESS 
to indicate the next location. See Appendix D for more information about 
debugger built-in symbols. 


The previous examples illustrates the use of the built-in symbols after 
referencing a symbolic name with the EXAMINE or DEPOSIT command. 
If you examine or deposit into a memory address, that location might 

or might not be associated with a compiler generated type. When you 
reference a memory address, the debugger uses the following convention to 
determine logical predecessors and successors: 


e Ifthe address has a symbolic name (the name of a variable, component 
of a composite variable, routine, and so on), the debugger uses the 
associated compiler generated type. 
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e Ifthe address does not have a symbolic name, the debugger uses the 
type longword integer by default. 


As the current entity is reset with new examine or deposit operations, the 
debugger associates each new location with a type in the manner indicated 
to determine logical successors and predecessors. This is illustrated in the 
next examples. 


Assume that a FORTRAN program has declared three variables, ARY, 
FLT, and BTE: 


e ARY is an array of three word integers (2 bytes each). 
e FLT is an F_floating type (4 bytes). 
e BTE is a byte integer (1 byte). 


Assume that storage for these variables has been allocated at consecutive 
addresses in memory, starting with 1000. For example: 


1000: ARY(1) 
1002: ARY(2) 
1004: ARY(3) 
1006: FLT 

1010: BTE 

1011: undefined 


Then, examining successive logical data locations would give the following 
results: 


DBG> EXAMINE 1000 ! Examine ARY(1), associated with 1000. 
MOD3\ARY(1): 13 ! Current entity is now ARY(1). 

DBG> EXAMINE ! Examine next location, ARY(2), 
MOD3\ARY (2): 7 ! using type of ARY(1) as reference. 
DBG> EXAMINE ! Examine next location, ARY(3). 
MOD3\ARY(3): 19 ! Current entity is now ARY(3). 

DBG> EXAMINE ! Examine entity at 1006 (FLT). 


MOD3\FLT: 1.9117807E+07 
DBG> EXAMINE 


Current entity is now FLT. 
Examine entity at 1010 (BTE). 


MOD3\BTE: 43 ! Current entity is now BTE. 
DBG> EXAMINE ! Examine entity at 1011 (undefined). 
1011: 17694732 ! Interpret data as longword integer. 
DBG> ! Location is not symbolized. 


The same principles apply when you use type qualifiers with the 
EXAMINE and DEPOSIT commands (see Section 4.5.2). The type specified 
by the qualifier determines the data boundary of an entity and, therefore, 


_any logical successors and predecessors. 


4.1.8 | Language Dependencies and the Current Language 
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The debugger enables you to set your debugging context to any one of 
several VAX-supported languages. The setting of the current language 
determines how the debugger parses and interprets the names, numbers, 


operators, and expressions you specify in debugger commands, and how it 
displays data. 


4.1.9 
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By default, the current language is the language of the module containing 
the main program, and it is identified when you invoke the debugger. For 
example: 


$ PASCAL/NOOPTIMIZE/DEBUG FORMS 
$ LINK/DEBUG FORMS 
S$ RUN FORMS 


VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is PASCAL, module set to ’FORMS’ 
DBG> 


When debugging modules whose code is written in other languages, you 
can use the SET LANGUAGE command to establish a new language 
dependent context. Section 9.3 highlights some important language 
differences. Appendix E identifies the operators and language constructs 
that are supported for each language (these are also identified if you type 
HELP LANGUAGE language-name at the debugger prompt). Be sure to 
consult the user’s guide of your language documentation for details on 
debugger support for that language. 


Specifying a Radix for Entering or Displaying Integer Data 


The debugger can interpret and display integer data in any one of four 
radixes: decimal, hexadecimal, octal, and binary. The default radix is 
decimal for all languages except BLISS and MACRO, and it is hexadecimal 
for BLISS and MACRO. 


You can control the radix for the following kinds of integer data: 
¢ Data that you specify in address expressions or language expressions. 
e Data that is displayed by the EVALUATE and EXAMINE commands. 


You cannot control the radix for other kinds of integer data. For example, 
addresses are always displayed in hexadecimal radix in a SHOW CALLS 
display. Or, when specifying an integer n with various command qualifiers 
(/AFTER:n, /UP:n, and so on) you must use decimal radix. 


The technique you use to control radix depends on your objective. To 
establish a new radix for all subsequent commands, use the SET RADIX 
command. For example: 


DBG> SET RADIX HEXADECIMAL 


After this command is executed, all integer data that you enter in address 
or language expressions is interpreted as being hexadecimal. Also, all 
integer data displayed by EVALUATE and EXAMINE commands is given 
in hexadecimal radix. 


The SHOW RADIX command identifies the current radix (which is either 
the default radix, or the radix last established by a SET RADIX command). 
For example: | 


DBG> SHOW RADIX 

input radix: hexadecimal 
output radix: hexadecimal 
DBG> 
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The SHOW RADIX command identifies both the input radix (for data 
entry) and the output radix (for data display). The SET RADIX command 
qualifiers [INPUT and /OUTPUT enable you to specify different radixes 
for data entry and display. See the command dictionary for additional 
information about the SET RADIX command. 


Use the CANCEL RADIX command to restore the default radix. 


The examples that follow show several techniques for displaying or 


entering integer data in another radix without changing the current 
radix. 


To convert some integer data to another radix without changing the 
current radix, use the EVALUATE command with a radix qualifier 
(/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL). For example: 


DBG> SHOW RADIX 

input radix: decimal 
output radix: decimal 
DBG> EVALUATE 18 + 5 


23 ! 23 is decimal integer. 
DBG> EVALUATE/HEX 18 + 5 

00000017 ! 17 is hexadecimal integer. 
DBG> ' 


The radix qualifiers do not affect the radix for data entry. 


To display the current value of an integer variable (or the contents of 
a program location that has an integer type) in another radix, use the 
EXAMINE command with a radix qualifier. For example: 


DBG> EXAMINE X 


MOD4\X: 4398 ! 4398 is a decimal integer. 
DBG> EXAMINE/OCTAL . ! X is the current entity. 
MOD4\X: 00000010456 ! 10456 is an octal integer. 
DBG> 


To enter one or more integer literals in another radix without changing 
the current radix, use one of the radix built-in symbols BIN, ZDEC, 
%HEX, or %OCT. A radix built-in symbol directs the debugger to treat an 
integer literal that follows (or all numeric literals in a parenthesized 
expression that follows) as a binary, decimal, hexadecimal, or octal 
number, respectively. These symbols do not affect the radix for data 
display. For example: 


DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 


DBG> EVAL %BIN 10 ! Evaluate the binary integer 10. 

2 ! 2 is a decimal integer. 

DBG> EVAL %HEX (10 + 10) ! Evaluate the hexadecimal integer 20. 

32 ! 32 is a decimal integer. 

DBG> EVAL %HEX 20 + 33 ! Treat 20 as hexadecimal, 33 as decimal. 
65 ! 65 is a decimal integer. 


DBG> EVAL/HEX %OCT 4672 


— 


Treat 4672 as octal and display in hex. 
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! OBA is a hexadecimal number. 


DBG> EXAMINE X + %SDEC 12 ! Examine the location 12 decimal bytes 


MOD3\X+12: 493847 


! beyond the address of X. 


DBG> DEPOS J = %OCT 7777777 ! Deposit an octal value. 


DBG> EXAMINE . 
MOD3\J: 2097151 


DBG> EXAMINE/OCTAL . 


MOD3\J3: 00007777777 


! Display that value in decimal radix. 


' Display that value in octal radix. 


DBG> EXAMINE %SHEX OA34D ! Examine location A34D, hexadecimal. 


SHARESLIBRTL+4941: 
DBG> 


Note: 


344938193 ! 344938193 is a decimal integer. 


When specifying a hexadecimal integer that starts with a letter 
rather than a number (for example, A34D in the last example), 
add a leading "0". Otherwise, the debugger tries to interpret the 
integer as a symbol declared in your program. 


See Appendix D for more examples showing the use of the radix built-in 
symbols. 


Obtaining and Symbolizing Memory Addresses 


Use the EVALUATE/ADDRESS command to determine the memory 
address or the register name associated with a symbolic address 
expression, such as a variable name, line number, routine name, or label. 
For example: 


DBG> EVALUATE/ADDRESS X ! A variable name 
2476 

DBG> EVALUATE/ADDRESS SWAP ! A routine name 
1536 

DBG> EVALUATE/ADDRESS %LINE 26 

1629 

DBG> 


The address is displayed in the current radix (as defined in Section 4.1.9). 
You can specify a radix qualifier to display the address in another radix. 


. For example: 


DBG> EVALUATE/ADDRESS/HEX X 
OOOO009AC 
DBG> 


If a variable is associated with a register instead of a memory address, 
the EVALUATE/ADDRESS command displays the name of the register, 
regardless of whether a radix qualifier is used. The following command 


indicates that variable K (a nonstatic variable) is associated with register 
R2: 

DBG> EVALUATE/ADDRESS K 

SR2 

DBG> 

Like the EXAMINE and DEPOSIT commands, EVALUATE/ADDRESS 
resets the values of the current, previous, and next logical-entity built-in 
symbols (see Section 4.1.7). Unlike the EVALUATE command, EVALUATE 


/ADDRESS does not affect the current-value built-in symbols, %CURVAL 
and backslash (\ ). 
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The command SYMBOLIZE does the reverse of EVALUATE/ADDRESS, 
but without affecting the current, previous, or next logical-entity built- 

in symbols. It converts a memory address or a register name into its 
symbolic representation (including its path name) if such a representation 
is possible (Chapter 5 explains how to control symbolization). For example, 
the following command shows that variable K is associated with register 
R2: 

DBG> SYMBOLIZE %R2 

address MOD3\%R2: 


MOD3\K 
DBG> 


By default, symbolic mode is in effect (SET MODE SYMBOLIC). Therefore 
the debugger displays all addresses symbolically, if symbols are available 
for the addresses. For example, if you specify a numeric address with the 
EXAMINE command, the address is displayed in symbolic form if symbolic 
information is available: 


DBG> EVALUATE/ADDRESS X 


2476 

DBG> EXAMINE 2476 
MOD3\X: 16 

DBG> 


However, if you specify a register that is associated with a variable, the 
EXAMINE command does not convert the register name to the variable 
name. For example: 


DBG> EVALUATE/ADDRESS K 
SR2 


DBG> EXAMINE %R2 
MOD3\%SR2: 78 
DBG> 


By entering the command SET MODE NOSYMBOLIC, you disable 
symbolic mode and cause the debugger to display numeric addresses 
rather than their symbolic names. When symbolization is disabled, the 
debugger might process commands somewhat faster because it does not 
need to convert numbers to names. The EXAMINE command has a 
/[LNOISYMBOLIC qualifier that enables you to control symbolization for a 
single EXAMINE command. For example: 


DBG> EVALUATE/ADDRESS Y 

512 

DBG> EXAMINE 512 

MOD3\Y: 28 

DBG> EXAMINE/NOSYMBOLIC 512 
512: 28 

DBG> 


Symbolic mode also affects the display of instructions. For example: 


DBG> EXAMINE/INSTRUCTION .%PC 
MOD5\%LINE 14+2: MOVAL L*MOD4\X,R11 
DBG> EXAMINE/NOSYMBOL/INSTRUCTION .%3PC 
1538: MOVAL L*1080,R11 

DBG> 
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Examining and Depositing into Variables 


Scalar Types 


The examples in this section illustrate how to use the EXAMINE and 
DEPOSIT commands with variables. 


Languages differ in the types of variables they use, the names for these 
types, and the degree to which different types can be intermixed in 
expressions. The following generic types are discussed in this section. 


e Scalars (such as integer, real, character, or Boolean) 


e Strings 
e Arrays 
¢ Records 


e Pointers (access types) 


The most important consideration when examining and manipulating 
variables in high-level language programs is that the debugger recognizes 
the names, syntax, type constraints, and scoping rules of the variables in 
your program. Therefore, when specifying a variable with the EXAMINE 
or DEPOSIT command, you use the same syntax that is used in the source 
code. The debugger processes and displays the data accordingly. Similarly, 
when assigning a value to a variable, the debugger follows the typing 
rules of the language. It issues a diagnostic message if you try to deposit 
an incompatible value. The examples in this section show some of these 
invalid operations and the resulting diagnostics. 


When using the DEPOSIT command (or any other command), note the 
following behavior. If the debugger issues a diagnostic message with 

a severity level of I (informational), the command is still executed (the 
deposit is made in this case). The debugger aborts an illegal command line 
only when the severity level of the message is W (warning) or greater. 


See your language documentation for additional examples and for 
information concerning any language features that are not supported 
by the debugger. 


The following examples illustrate use of the EXAMINE, DEPOSIT, and 
EVALUATE commands with some integer, real, and Boolean types. 


Examine a list of three integer variables: 


DBG> EXAMINE WIDTH, LENGTH, AREA 


SIZE\WIDTH: 4 
SIZE\LENGTH: 7 
SIZE\AREA: 28 
DBG> 


Deposit an integer expression: 


DBG> DEPOSIT WIDTH = CURRENT WIDTH + 10 
DBG> 
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The debugger checks that a value to be assigned is compatible with the 
data type and dimensional constraints of the variable. The following 
example shows an attempt to deposit an out-of-bounds value (X was 
declared as a positive integer): 


DBG> DEPOSIT XK = -14 
SDEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT 
DBG> 


If you try to mix numeric types (integer and real of varying precision) 

in a language expression, the debugger generally follows the rules of 

the language. Strongly typed languages do not allow much if any mixing. 
With some languages, you can deposit a real value into an integer variable. 
However, the real value is converted into an integer. For example: 


DBG> DEPOSIT I = 12345 
DBG> EXAMINE I 

MOD3\I: 12345 

DBG> DEPOSIT I = 123.45 
DBG> EXAMINE I 

MOD3\I: 123 

DBG> 


Note that, if numeric types are mixed in an expression, the debugger 
performs type conversion as discussed in Section 4.1.5.2. For example: 


DBG> DEPOSIT Y = 2.356 ! Y is of type D floating point. 
DBG> EXAMINE Y 

MOD3\Y: 2.35600000000000 

DBG> EVALUATE Y + 3 

5.35600000000000 


DBG> DEPOSIT R = 5.35E3 ! Ris of type F_ floating point. 
DBG> EXAMINE R 
MOD3\R: 5350.000 
DBG> EVALUATE R*50 
267500.0 
DBG> DEPOSIT I = 22222 
DBG> EVALUATE R/I 
0.2407524 
DBG> 


The next example shows some operations with Boolean variables. The 
values TRUE and FALSE are assigned to the variables WILLING and 
ABLE, respectively. The EVALUATE command then obtains the logical 
conjunction of these values: 


DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 

DBG> EVALUATE WILLING AND ABLE 
False 

DBG> 


4.2.2 ASCII String Types 


When displaying an ASCII string value, the debugger encloses it within 
quotation marks (") or apostrophes (’ ), depending on the language syntax. 


4-16 


4.2.3 


Array Types 


Examining and Manipulating Program Data 
4.2 Examining and Depositing into Variables 


For example: 


DBG> EXAMINE EMPLOYEE NAME 
PAYROLL\EMPLOYEE NAME: "Peter C. Lombardi" 
DBG> 


To deposit a string value (including a single character) into a string 
variable, you must enclose the value in quotation marks (") or apostrophes 
(’). For example: 


DBG> DEPOSIT PART NUMBER = "WG-7619.3-84" 
DBG> 


If the string has more ASCII characters (1 byte each) than can fit into the 
location denoted by the address expression, the debugger truncates the 
extra characters from the right and issues the following message: 


SDEBUG-I-ISTRTRU, string truncated at or near DEPOSIT 


If the string has fewer characters, the debugger pads the remaining 
characters to the right of the string by inserting ASCII space characters. 


You can examine an entire array aggregate, a single indexed element, or a 
slice (a range of elements). But you can deposit into only one element at a 
time. The following examples show typical operations with arrays. 


The following command displays the values of all the elements of the array 
variable ARRX, a one-dimensional array of integers: 


DBG> EXAMINE ARRX 


MOD3 \ARRX 
oe ee 42 
(2) 17 
(3): 273 
(4): 56 
(3). Ls 
(6): 149 

DBG> 


The following command displays the value of element 4 of array ARRX 
(depending on the language, parentheses or brackets are used to denote 
indexed elements): 


DBG> EXAMINE ARRX (4) 
MOD3\ARRX (4) : 56 
DBG> 


The following command displays the values of all the elements in a slice 
of ARRX. This slice consists of the range of elements from element 2 to 
element 5: 


DBG> EXAMINE ARRX (2:5) 


MOD3 \ARRX 
(2): se 
(3)-2 278 
(4): 56 
(5): L13 
DBG> 
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In general, a range of values to be examined is denoted by two values 
separated by a colon (valuel:value2). Depending on the language, two 
periods (..) can be used instead of a colon. 


You can deposit a value to only a single array element at a time (you 
cannot deposit to an array slice or an entire array aggregate with a single 
DEPOSIT command). For example, the following command deposits the 
value 53 into element 2 of ARRX: 


DBG> DEPOSIT ARRX(2) = 53 
DBG> 


The following command displays the values of all the elements of array 
REAL_ARRAY, a two-dimensional array of real numbers (three per 
dimension): 


DBG> EXAMINE REAL ARRAY 
PROG2\REAL ARRAY 


(1,1): 27.01000 
(1,2): 31.00000 
(1,3): 12.48000 
(2,1): 15.08000 
(2,2): 22.30000 
(2,3): 18.73000 

DBG> 


The debugger issues a diagnostic message if you try to deposit to an index 
value that is out of bounds. For example: 


DBG> DEPOSIT READ ARRAY (ly 4) = 26.13 
SDEBUG-~I-SUBOUTBND, subscript 2 is out of bounds, value is 4, bounds are 1..3 


DBG> 


Record Types 
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Note that, in the previous example the deposit operation was executed 
because the diagnostic message is of I level. This means that the value 
of some array element adjacent to (1,3), possibly (2,1) might have been 
affected by the out-of-bounds deposit operation. 


To deposit the same value to several components of an array, you can use a 
looping command, such as FOR or REPEAT. For example, assign the value 
RED to elements 1 to 4 of the array COLOR_ARRAY: 


DBG> FOR I = 1 TO 4 DO (DEPOSIT COLOR ARRAY (I) = RED) 
DBG> 


You can also use the built-in symbols (.) and (“) and the Return key to 
step through array elements, as explained in Section 4.1.7. 


You can examine an entire record aggregate, a single record component, 
or séveral components. But you can deposit into only one component at a 
time. The following examples show typical operations with records. 
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The following command displays the values of all the components of the 
record variable PART: 


DBG> EXAMINE PART 
INVENTORY \PART: 
ITEM: "WE-1247" 
PRICE: 49.95 
IN STOCK: 24 
DBG> 


The following command displays the value of component IN_STOCK of 
record PART (general syntax): 


DBG> EXAMINE PART.IN STOCK 
INVENTORY\PART.IN STOCK: 24 
DBG> 


The following command displays the value of the same record component, 
using COBOL syntax (the language must be set to COBOL): 


DBG> EXAMINE IN STOCK OF PART 

INVENTORY\IN STOCK of PART: 
IN STOCK: 24 

DBG> 


The following command displays the values of two components of record 


PART: 

DBG> EXAMINE PART.ITEM, PART.IN STOCK 
INVENTORY \PART.ITEM: "WE-1247" 
INVENTORY\PART.IN STOCK: 24 

DBG> 


The following command deposits a value into record component 
IN_STOCK: 


DBG> DEPOSIT PART.IN STOCK = 17 
DBG> 


4.2.5 Pointer (Access) Types 


You can examine the entity designated (pointed to) by a pointer variable 
and deposit a value into that entity. You can also examine a pointer 
variable. 


For example, the following Pascal code declares a pointer variable A that 
designates a value of type real: 
TYPE 

T = “REAL; 


VAR 
A: sD 


The following command displays the value of the entity designated by the 
pointer variable A: 


DBG> EXAMINE A* 
MOD3\A*: 1.7 
DBG> 
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In the following example, the value 3.9 is deposited into the entity 
designated by A: 


DBG> DEPOSIT A®* = 3.9 
DBG> EXAMINE A%* 
MOD3\A*: 3.9 

DBG> 


When you specify the name of a pointer variable with the EXAMINE 
command, the debugger displays the memory address of the object it 
designates. For example: 


DBG> EXAMINE/HEXADECIMAL A 
SAMPLE\A: OOQOB2A4 
DBG> 


4.3 Examining and Depositing VAX Instructions 


The debugger recognizes address expressions that are associated with VAX 
assembly language instructions. This enables you to examine and deposit 
instructions using the same basic techniques as with variables. 


When debugging at the instruction level, you might find it convenient 
to first enter the following command. It sets the default step mode to 
stepping by instruction: 


DBG> SET STEP INSTRUCTION 
DBG> 


There are other step modes that enable you to execute the program to 
specific kinds of instructions (INSTRUCTION/=opcode/, CALL, BRANCH, 
and so on). Also you can set breakpoints to interrupt execution on 
every instruction or on instructions of a particular class (SET BREAK 
JINSTRUCTION/=opcode/, /CALL, and so on). 


In addition you can use a screen-mode instruction display (see 
Section 7.2.4), to display the actual decoded instruction stream of your 
program. 


4.3.1 Examining VAX Instructions 
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If you specify an address expression that is associated with an instruction 
in an EXAMINE command (for example, a line number), the debugger 
displays the first instruction at that location. You can then use the period 
(.), Return key, and circumflex character (“) to display the current, next, 
and previous instruction (logical entity), as described in Section 4.1.7. For 
example: 


DBG> EXAMINE %SLINE 12 


MOD3\%SLINE 12: MOVL (R11) ,B%*%16 (R11) 

DBG> EXAMINE 

MOD3\%LINE 12+4: MOVL S*#1,B*4(R11) ! Next instruction. 
DBG> EXAMINE 

MOD3\%LINE 12+8: TSTL B*16 (R11) ! Next instruction. 
DBG> EXAMINE %* 

MOD3\%SLINE 12+4: MOVL S*#1,B*°4(R11) ! Previous instruction. 
DBG> 


Examining and Manipulating Program Data 
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Line numbers, routine names, and labels are symbolic address expressions 
that are associated with instructions. In addition, instructions might be 
stored at various other memory addresses and in certain registers during 
the execution of your program. 


The program counter (PC) is the register that contains the address of the 
next instruction to be executed by your program. The command EXAMINE 
.%PC displays that instruction. The period (.), when used directly in front 
of an address expression, denotes the "contents of" operator—that is, the 
contents of the location designated by the address expression. Note the 
following distinction: 


e EXAMINE %PC displays the current PC value, namely the address of 
the next instruction to be executed. 


e EXAMINE .%PC displays the contents of that address, namely the 
next instruction to be executed by the program. 


When you enter the command EXAMINE .%PC, you can control the 
amount of information displayed by using the /OPERANDS qualifier. For 


example: 

DBG> EXAMINE .%PC 

MOD3\%LINE 12: MOVL B12 (R11), Ri 

DBG> EXAMINE/OPERANDS .%PC 

MOD3\%LINE 12: MOVL B*12(R11),R1 
B*12(R11) MOD3\K (address 1196) contains 1 
R1 Rl contains 8 

DBG> EXAMINE/OPERANDS=FULL .%PC 

MOD3\%LINE 12: MOVL B*12(R11),R1 


B*12(R11) R11 contains MOD3\N (address 1184), B*12(1184) evaluates to 
MOD3\K (address 1196), which contains 1 
R1 Rl contains 8 
DBG> 


Use the /OPERANDS qualifier only when examining the current PC 
instruction. The information might not be reliable if you specify other 
locations. The command SET MODE [NOJOPERANDS enables you to 
control the default behavior of the command EXAMINE .%PC. 


As shown in the previous examples, the debugger knows whether 

an address expression is associated with an instruction. If it is, the 
EXAMINE command displays that instruction (you do not need to use 
the /INSTRUCTION qualifier). You use the INSTRUCTION qualifier 

to display the contents of an arbitrary program location as a VAX 
instruction—that is, the command EXAMINE/INSTRUCTION causes 

the debugger to interpret and format the contents of any program location 
as a VAX instruction (see Section 4.5.2). 


Note that, when you examine consecutive instructions in a MACRO 
program, the debugger might misinterpret data as instructions if storage 
for the data is allocated in the middle of a stream of instructions. The 
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following example shows some MACRO code with two longwords of data 
storage allocated directly after the BRB instruction at line 7 (line numbers 
have been added to the example for clarity): 


module TEST 


lies TITLE TEST 

2: 

3: TESTSSTART:: 

4: . WORD 0 

os 

6: MOVL #2,R2 

fa BRB LABEL 2 

8: 

9; . LONG “X12345 
10: . LONG “X14465 
Lis 
12: LABEL 2: 
13s MOVL #5,R5 
14; 

Ais ys. . END TESTSSTART 


The following examine command displays the instruction at the start of 
line 6: 


DBG> EXAMINE «LINE 6 
TEST\TESTSSTART\SLINE 6: MOVL S*#02,R2 
DBG> 


The following examine command correctly interprets and displays the 
logical successor entity as an instruction, at line 7: 


DBG> EXAMINE 
TEST\TESTSSTART\%LINE 7: BRB TEST\TESTSSTART\LABEL 2 
DBG> 


However, the following three examine commands incorrectly interpret the 
three logical successors as instructions: 


DBG> EXAMINE 

TEST\TESTSSTART\SLINE 7+2: MULF3 S*#11.00000, S*#0.5625000, S*#0.5000000 
DBG> EXAMINE 

SDEBUG-W-ADDRESSMODE, instruction uses illegal or undefined addressing modes 
TEST\TESTSSTART\SLINE 7+6: MULD3 S*#0.5625000 [R4],S*#0.5000000, @W*5505 (RO) 
DBG> EXAMINE 

TESTSSTART+12: HALT 

DBG> 


Depositing VAX Instructions 


When depositing a VAX instruction, use the following command format: 
DEPOSIT/INSTRUCTION address-expression = "VAX instruction" 


You must enclose the instruction in either quotation marks or apostrophes. 
You must also use the /INSTRUCTION qualifier with the DEPOSIT 
command, to indicate that the delimited string is an instruction and not 
an ASCII string. Or, if you plan to deposit several instructions, you can 
first enter the command SET TYPE/OVERRIDE INSTRUCTION (see 
Section 4.5.2). You then do not need to use the [INSTRUCTION qualifier 
on the DEPOSIT command. 
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VAX instructions occupy different numbers of bytes, depending on their 
operands. When depositing VAX instructions of arbitrary lengths into 
successive memory locations, use the logical successor operator (Return 
key) to establish the next unoccupied location where an instruction can be 
deposited. The following example illustrates the technique. 


DBG> SET TYPE/OVERRIDE/INST ! Set the default type to instruction. 

DBG> DEPOSIT 730 = "MOVB #77, R1" ! Deposit an instruction beginning at address 730. 
DBG> EXAMINE . ! Examine the current entity to verify the deposit. 
730: MOVB’ #77,R1 

DBG> EXAMINE [RET] ! Make the logical successor the new current entity. 
734: HALT 

DBG> DEPOSIT . = "MOVB #66, R2"  ! Deposit the next instruction. 

DBG> EXAMINE . ! Display and verify the deposit. 

734: MOVB' #66,R2 

DBG> 


When you replace an instruction, be sure that the new instruction, 
including operands, is the same length in bytes as the old instruction. 

If the new instruction is longer, you cannot deposit it without overwriting, 
and thereby destroying, the next instruction. If the new instruction 
occupies fewer bytes of memory than the old one, you must deposit NOP 
instructions (instructions that cause "no operation") in bytes of memory 
left unoccupied after the replacement. The debugger does not warn you if 
an instruction you are depositing will overwrite a subsequent instruction, 
nor does it remind you to fill in vacant bytes of memory with NOPs. 


The following example illustrates how to replace an instruction with an 
instruction of equal length. 


DBG> SET STEP INSTRUCTION ! Step by instruction. 
DBG> STEP 

stepped to 1584: PUSHAL (R11) 

DBG> STEP 


stepped to 1586: CALLS #1,L*%2224 ! Instruction to be replaced. 
DBG> EXAMINE .%PC 


1586: CALLS #1,L%2224 


DBG> EXAMINE ! Determine start of next 
1593: CALLS #0, L*2216 ! instruction (1593). 
DBG> DEPOSIT/INST 1586 = "CALLS #2,L*°2224" 

! Deposit new instruction. 
DBG> EXAMINE . ! Verify that instruction 
1586: CALLS #2,L°2224 ! is deposited. 
DBG> EXAMINE ! Verify that the next 
1593: CALLS #0,L°2216 ! instruction is unchanged. 
DBG> 





Examining and Depositing into Registers 


Note: See Chapter 11 for information about the VAX vector registers. 


The VAX architecture provides 16 general registers, some of which are 
used for temporary address and data storage. When referencing a register 
in a debugger command, use the following built-in symbols (the register 
name preceded by a percent sign (% )). 
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Symbol Description 


%RO... %R11 General purpose registers (RO... R11) 


%AP (%R12) Argument pointer (AP) 

%FEP (%R13) Frame pointer (FP) 

%SP (%R14) Stack pointer (SP) 

%PC (%R15) Program counter (PC) 

%PSL Processor status longword (PSL) 


You can omit the percent sign (%) prefix if your program has not declared 
a symbol with the same name. 


You can examine the contents of all the registers. You can deposit values 


into all the registers except for SP. Use caution when depositing values 
into FP. 


The following examples show how to examine and deposit into registers. 


DBG> SHOW TYPE ! Show type for locations without 
type: long integer ! a compiler generated type. 
DBG> SHOW RADIX ! Identify current radix. 


input radix: decimal 

output radix: decimal 

DBG> EXAMINE ¢R11 ! Display value in Rll. 
MOD3\%R11: 1024 

DBG> DEPOSIT sR1l = 444 ! Deposit new value into R11. 


DBG> EXAMINE %R11 ! Check new value. 

R11: 444 

DBG> EXAMINE SPC ! Display value in program counter. 
MOD\%SPC: 1553 

DBG> EXAMINE %SP ! Display value in stack pointer. 
O\SSP: 2147278720 

DBG> 


See Section 4.3.1 for specific information about the PC. 


4.4.1. The Processor Status Longword (PSL) 
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The PSL is a register whose value represents a number of processor 
state variables. The first 16 bits of the PSL (referred to separately as the 
processor status word, or PSW) contain unprivileged information about 
the current processor state. The values of these bits can be controlled 
by a user program. The latter 16 bits of the PSL, bits 16 to 31, contain 
privileged information and cannot be altered by a user-mode program. 


The following example shows how to examine the contents of the PSL: 


DBG> EXAMINE <PSL 
MOD3\PSL: 
CMP TP FPD IS CURMOD PRVMOD IPL DV FUIVTNZVC 
nnn 


n nn n mode mode lv nonononny»”»a 
DBG> 


See the VAX Architecture Handbook for complete information about the 
PSL, including the values of the various bits. 
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You can also display the information in the PSL in other formats. For 


example: 

DBG> EXAMINE/LONG/HEX %PSL 

MOD3\%PSL: 03C00010 

DBG> EXAMINE/LONG/BIN %PSL 

MOD3\%PSL: 00000011 11000000 00000000 00010000 
DBG> 


The command EXAMINE/PSL displays the value at any location in PSL 
format. This is useful for examining saved PSLs on the call stack. 


To disable all conditions in the PSL, clear bits 0 to 15 with the following 
DEPOSIT command: 


DBG> DEPOSIT/WORD PSL = 0 
DBG> EXAMINE PSL 
MOD3\PSL: 
CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN 
00 0 


Vc 
0 0 QO QO USER USER 0 0 0 0 0 


On 


DBG> 


4.5 Specifying a Type When Examining and Depositing 


The preceding sections explain how to use the EXAMINE and DEPOSIT 
commands with program locations that have a symbolic name and, 
therefore, are associated with a compiler generated type. 


Section 4.5.1 describes how the debugger formats (types) data for program 
locations that do not have a symbolic name and explains how you can 
control the type for those locations. 


Section 4.5.2 explains how to override the type associated with any 
program location, including a location that has a symbolic name. 


4.5.1. Defining a Type for Locations Without a Symbolic Name 


Program locations that do not have a symbolic name and, therefore, are 
not associated with a compiler generated type have the type longword 
integer by default. Section 4.1.4 explains how to examine and deposit into 
such locations using the default type. 


The SET TYPE command enables you to change the default type. This 
is useful if you want to examine and display the contents of a location in 
another type, or if you want to deposit a value of some particular type 
into a location that is associated with another type. The possible type 
keywords are as follows: 


ASCIC CONDITION_VALUE INSTRUCTION QUADWORD 


ASCID D_ FLOAT LONGWORD TYPE=(type-expression) 
ASCIl:n DATE_TIME OCTAWORD WORD 

ASCIW FLOAT PACKED 

ASCIZ G_FLOAT PSL 

BYTE H_ FLOAT PSW 
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For example, the following commands set the type for locations without 
a symbolic name to, respectively, byte integer, G_float, and ASCII with 6 
bytes of ASCII data. Each successive SET TYPE command resets the type: 


DBG> SET TYPE BYTE 


DBG> SET TYPE G FLOAT 
DBG> SET TYPE ASCII:6 


Note that the SET TYPE command, when used without the /OVERRIDE 
qualifier, does not affect the type for program locations that have a 
symbolic name (locations associated with a compiler generated type). 


The SHOW TYPE command identifies the current type for locations 
without a symbolic name. To restore the default type for such locations, 
enter the command SET TYPE LONGWORD. 


4.5.2  Overriding the Current Type 
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The SET TYPE/OVERRIDE command enables you to change the type 
associated with any program location, thereby overriding any compiler 
generated type. For example, after the following command is executed, 
an unqualified EXAMINE command displays the contents of only the first 
byte of the location specified and interprets the contents as byte integer 
data. An unqualified DEPOSIT command modifies only the first byte of 
the location specified and formats the data deposited as byte integer data. 


DBG> SET TYPE/OVERRIDE BYTE 


To identify the current override type, enter the command SHOW TYPE 
/OVERRIDE. To cancel the current override type and restore the normal 


interpretation of locations that have a symbolic name, enter the command 
CANCEL TYPE/OVERRIDE. 


Type qualifiers, used with the EXAMINE and DEPOSIT commands, enable 
you to override the type currently associated with a program location for 
the duration of a single EXAMINE or DEPOSIT command. The type 
qualifiers are as follows: 


IASCIC = /CONDITION_VALUE /INSTRUCTION /QUADWORD 


/ASCID) /D_FLOAT /LONGWORD [TASK 

/ASCliiin = /DATE_TIME /OCTAWORD /TYPE=(type-expression) 
/ASCIW — /FLOAT /PACKED /WORD 

/ASCIZ /G_FLOAT /PSL 

/BYTE /H_FLOAT /PSW 


These qualifiers override any previous SET TYPE or SET TYPE 
/OVERRIDE command as well as any compiler generated type. 
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When used with a type qualifier, the EXAMINE command displays the 
entity specified by the address expression in that type. For example: 


DBG> EXAMINE %LINE 15 ! Display line 15 in compiler 
MOD3\%LINE 15 : MOVL #1,B*44(R11)! generated type: instruction. 
DBG> EXAMINE/BYTE . ! Type is byte integer. 
MOD3\%LINE 15 : -48 

DBG> EXAMINE/WORD . ! Type is word integer. 
MOD3\%LINE 15 : 464 

DBG> EXAMINE/LONG . ! Type is longword integer. 
MOD3\%LINE 15 : 749404624 

DBG> EXAMINE/QUAD . ! Type is quadword integer. 
MOD3%LINE 15 : +0130653502894178768 

DBG> EXAMINE/FLOAT . ! Type is F_ floating. 
MOD3%LINE 15 : 1.9117807E-38 

DBG> EXAMINE/G FLOAT . ! Type is G floating. 
MOD3%LINE 15 : 1.509506018605227E-300 

DBG> EXAMINE/INSTRUCTION . ! Type is VAX instruction. 
MOD3\%SLINE 15 : MOVL #1,B%*44 (R11) 

DBG> EXAMINE/ASCII . ! Type is ASCII string. 
MOD3\SLINE 15 : "™.." 

DBG> 


When used with a type qualifier, the DEPOSIT command deposits a 
value of that type into the location specified by the address expression, 
overriding the type associated with the address expression. 


The remaining sections provide examples of specifying integer, string, and 
user-declared types with type qualifiers and the SET TYPE command. 


4.5.2.1 Integer Types 
The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with integer type qualifiers (/BYTE, /WORD, /LONGWORD). 
These qualifiers enable you to deposit a value of a particular integer type 
into an arbitrary program location. 


DBG> SHOW TYPE ! Show type for locations without 

type: long integer ! a compiler generated type. 

DBG> EVALU/ADDR . i Current location is 724. 

724 

DBG> DEPO/BYTE . = 1 ! Deposit the value 1 into one byte 
! of memory at address 724. 

DBG> EXAM . ! By default, 4 bytes are examined. 

724: 1280461057 

DBG> EXAM/BYTE . ! Examine one byte only. 

724: 1 

DBG> DEPO/WORD . = 2 ! Deposit the value 2 into first two 
! bytes (word) of current entity. 

DBG> EXAM/WORD . ! Examine a word of the current entity. 

724: 2 


DBG> DEPO/LONG 724 


999 ! Deposit the value 999 into 4 bytes 
!(a longword) beginning at address 724. 


DBG> EXAM/LONG 724 ! Examine 4 bytes (longword) 
724: 999 ! beginning at address 724. 
DBG> 
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4.5.2.2 ASCII String Type 
The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with the /ASCII:n type qualifier. 


When used with the DEPOSIT command, this qualifier enables you to 
deposit an ASCII string of length n into an arbitrary program location. 
In the example, the location has a symbolic name (I) and, therefore, is 
associated with a compiler generated integer type. The command format 
is as follows: 


DEPOSIT/ASCII:n address-expression = "ASCII string of length n" 
The default value of n is 4 bytes. 


DBG> DEPOSIT I = "abcde" ! I has compiler generated integer type. 
%DEBUG-W-INVNUMBER, invalid numeric string ’abcde’ 
! So, cannot deposit string into I. 


DBG> DEP/ASCII:5 I = "abcde"! /ASCII qualifier overrides integer 
! type to deposit 5 bytes of 
! ASCII data. 
DBG> EXAMINE . ! Display value of I in compiler 
MOD3\I: 1146048327 ! generated integer type. 
DBG> EXAM/ASCII:5 . ! Display value of I as 5-byte 
MOD3\I: "abcde" ! ASCII string. 
DBG> 


If you want to enter several DEPOSIT/ASCIT commands, you can establish 
an override ASCII type with the SET TYPE/OVERRIDE command. 
Subsequent EXAMINE and DEPOSIT commands then have the effect 

of specifying the /ASCII qualifier with these commands. For example: 


DBG> SET TYPE/OVER ASCII:5! Establish ASCII:5 as override type.) 


DBG> DEPOSIT I = "abcde" ! Can now deposit 5-byte string into I.) 
DBG> EXAMINE I ! Display value of I as 5-byte) 

MOD3\I: "abcde" ! ASCII string. 

DBG> CANCEL TYPE/OVERRIDE ! Cancel ASCII override type. 

DBG> EXAMINE I ! Display I in compiler generated type. 
MOD3\I: 1146048327 

DBG> 


4.5.2.3. User-Declared Types 
The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with the /TYPE=(type-expression) qualifier. The qualifier 
enables you to specify a user-declared override type when examining 
or depositing. 


For example, assume that a Pascal program contains the following code, 
which declares the enumeration type COLOR with the three values RED, 
GREEN, and BLUE: 
TYPE 

COLOR = (RED, GREEN, BLUE) ; 


During the debugging session, the SHOW SYMBOL/TYPE command 
identifies the type COLOR as it is known to the debugger: 


DBG> SHOW SYMBOL/TYPE COLOR 

data MOD3\COLOR | 
enumeration type (COLOR, 3 elements), size: 1 byte 

DBG> 
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The next command displays the value at address 1000, which is not 
associated with a symbolic name. Therefore, the value 0 is displayed in 
the type longword integer, by default: 


DBG> EXAMINE 1000 
1000: 0 
DBG> 


The next command displays the value at address 1000 in the type COLOR. 
The preceding SHOW SYMBOL/TYPE command indicates that each 
enumeration element is stored in 1 byte. Therefore, the debugger converts 
the first byte of the longword integer value 0 at address 1000 to the 
equivalent enumeration value, RED (the first of the three enumeration 
values): 


DBG> EXAMINE/TYPE=(COLOR) 1000 
L000: RED 
DBG> 


The following DEPOSIT command deposits the value GREEN into address 
1000 with the override type COLOR. The EXAMINE command displays 
the value at address 1000 in the default type, longword integer: 


DBG> DEPOSIT/TYPE=(COLOR) 1000 = GREEN 
DBG> EXAMINE 1000 

1000: a 

DBG> 


The following SET TYPE command establishes the type COLOR for 
locations, such as address 1000, that do not have a symbolic name. The 
EXAMINE command now displays the value at 1000 in the type COLOR: 


DBG> SET TYPE TYPE= (COLOR) 
DBG> EXAMINE 1000 

1000: GREEN 

DBG> 
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Symbolic debugging enables you to specify variable names, routine names, 
and so on, precisely as they appear in your source code. You do not need 
to use numeric memory addresses or registers when referring to program 
locations, although you can, if you want. 


In addition, you can use symbols in the context that is appropriate for the 
program and its source language. The debugger supports the language 
conventions regarding data types, expressions, scope and visibility of 
entities, and so on. 


To have full access to the symbols that are associated with your program, 
you must compile and link the program using the /DEBUG DCL command 
qualifier. 


Under these conditions, the way in which symbol information is passed 
from your source program to the debugger and is processed by the 
debugger is transparent to you in most cases. However, certain situations 
might require some action. 


For example, when you try to set a breakpoint on a routine named 
COUNTER, the debugger might display the following diagnostic message: 


DBG> SET BREAK COUNTER 
SDEBUG-E-NOSYMBOL, symbol ‘COUNTER’ is not in the symbol table 
DBG> 


You must then set the module where COUNTER is defined, as explained 
in Section 5.2. 


Or, the debugger might display the following message if the same symbol 
X is defined (declared) in more than one module, routine, or other program 
unit: 

DBG> EXAMINE X 


SDEBUG-E-NOUNIQUE, symbol ’X’ is not unique 
DBG> 


You must then resolve the symbol ambiguity, perhaps by specifying a path 
name for the symbol, as explained in Section 5.3. 


This chapter explains how to handle these and other situations related to 
accessing symbols in your program. 


The chapter discusses only the symbols (typically address expressions) 
that are derived from your source program, for example: 


e The names of entities that you have declared in your source code, such 
as variables, routines, labels, array elements, or record components. 


e The names of modules (compilation units) and shareable images that 
are linked with your program. 
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Note: 


e Elements that the debugger uses to identify source code—for example, 
the specifications of source files, and source line numbers as they 
appear in a listing file or when the debugger displays source code. 


The following types of symbols are discussed in other chapters: 


e The symbols you create during a debugging session with the DEFINE 
command are covered in Section 8.4. 


e The debugger’s built-in symbols, such as the period (.) and %PC are 
tabulated in Appendix D and discussed throughout this manual in the 
appropriate context. 


Also, see Section 4.1.10 for information about how to obtain the 
memory addresses and register names associated with symbolic address 
expressions and how to symbolize program locations. 


If your program was optimized during compilation, certain 
variables in the program might be removed by the compiler. If 
you then try to reference such a variable, the debugger issues a 
warning (see Section 9.1). 


Before you try to reference a nonstatic (stack-local or register) 
variable, its defining routine must be active on the call stack. That 
is, program execution must be suspended somewhere within the 
defining routine (see Section 3.6.2). 


5.1 Controlling Symbol Information When Compiling and Linking 
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To take full advantage of symbolic debugging, you must compile and 

link your program with the /DEBUG qualifier. The following example 
illustrates these steps with a simple Pascal program, INVENTORY, that 
consists of two compilation units whose source code is in two separate files, 
FORMS.PAS and INVENTORY.PAS. INVENTORY is the main program 
unit: 

$ PASCAL/NOOPTIMIZE/DEBUG FORMS, INVENTORY 

$ LINK/DEBUG INVENTORY, FORMS 


Note that the /NOOPTIMIZE qualifier is used with the compiler command 
(PASCAL, in this example). If the compiler optimizes code by default, it is 
best to disable this feature by specifying /NOOPTIMIZE (or the equivalent 
qualifier, if any, for your compiler). Otherwise, the resulting object code is 
optimized, possibly causing the contents of some program locations to be 
inconsistent with what you might expect from looking at the source code. 
(Section 9.1 describes some of the effects of optimization.) 


The next sections describe how symbol information is created and passed 
to the debugger when compiling and linking. 


3.1.1 


Compiling 
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5.1 Controlling Symbol Information When Compiling and Linking 


When you compile a source file using the /DEBUG qualifier, the compiler 
creates symbol records for the debug symbol table (DST records) and 
includes them in the object module being generated (such as the compiler 
output file FORMS.OBJ, in the previous example). 


DST records provide not only the names of symbols but also all relevant 
information about their use. For example: 


¢ Data types, ranges, constraints, and scopes associated with variables. 


e Parameter names and parameter types associated with functions and 
procedures. 


e Source line correlation records, which associate source lines with line 
numbers and source files. 


Most compilers allow you to vary the amount of DST information put 
in an object module by specifying different options with the /DEBUG 
qualifier. Table 5—1 identifies the options for most compilers (refer to the 
documentation supplied with your compiler for complete information). 


Table 5-1 Compiler Options for DST Symbol Information 


Compiler Command 


Qualifier DST Information in Object Module 

/DEBUG' Full 

/DEBUG=TRACEBACK? Traceback only (module names, routine names, and 
line numbers) 

/NODEBUG? None 


'/DEBUG, /DEBUG=ALL, and /DEBUG=(SYMBOLS, TRACEBACK) are equivalent. 
2/DEBUG=TRACEBACK and DEBUG=(NOSYMBOLS, TRACEBACK) are equivalent. 
3/NODEBUG, /DEBUG=NONE, and /DEBUG=(NOSYMBOLS,NOTRACEBACK) are equivalent. 


The TRACEBACK option is a default for most compilers. That 

is, if you omit the DEBUG qualifier, most compilers assume 
/DEBUG=TRACEBACK. The TRACEBACK option enables the VMS 
traceback condition handler to translate memory addresses into routine 
names and line numbers so that it can give a symbolic traceback if a 
run-time error has occurred. For example: 


S RUN INVENTORY 


SPAS-F-ERRACCFIL, error in accessing file PASSOUTPUT 
%$PAS~F-ERROPECRE, error opening/creating file 
SRMS-F-FNM, error in file name 

STRACE~F-TRACEBACK, symbolic stack dump follows 


module name routine name line rel PC abs PC 
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Linking 


PASSIO BASIC  —_ PASSCODE 00000192 00001CED 
PASSIO BASIC —_ PASSCODE 0000054D 000020a8 
PASSIO BASIC  _ PASSCODE 0000028B 00001DE6 
INVENTORY INVENTORY 59 00000020 000005A1 
$ 


Traceback information is also used by the debugger’s SHOW CALLS 
command. 


Local and Global Symbols 


DST records contain information about all of the symbols that are defined 
in your program. These are either local or global symbols. 


Typically, local symbols are symbols that are referenced only within the 
module where they are defined; global symbols are symbols such as routine 
names, procedure entry points, and global data names, that are defined in 
one module but referenced in other modules. 


Generally, the compiler resolves references to local symbols, and the linker 
resolves references to global symbols. 


The distinction between local and global symbols is discussed in this 
chapter in connection with symbol lookup and with shareable images and 
universal symbols. 


When you enter the command LINK/DEBUG to link object modules and 
produce an executable image, the linker performs several functions that 
affect debugging: 


e¢ It builds a debug symbol table (DST) from the DST records contained 
in the object modules being linked. The DST is the primary source of 
symbol information during a debugging session. 


¢ It resolves references to global symbols and builds a global symbol 
table (GST). The GST duplicates some of the global symbol information 
already contained in the DST, but the GST is used by the debugger for 
symbol lookup under certain circumstances. 


¢ It puts the DST and GST in the executable image. 


e §6It sets flags in the executable image that cause the image activator to 
pass control to the debugger when you enter the RUN command. 


Table 5-2 summarizes the level of DST and GST information passed to 
the debugger depending on the compiler or LINK command option. The 
compiler command qualifier controls the level of DST and GST information 
passed to the linker. The LINK command qualifier controls not only how 
much of that information is passed to the debugger but also how (or if) you 
can invoke the debugger. 
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Table 5-2 Effect of Compiler and Linker on DST and GST Symbol Information 


Compiler LINK 
Command DST Data in Command 
Qualifier’ Object Module Qualifier 
/DEBUG Full /DEBUG 
/DEBUG=TRACE _ Traceback only /DEBUG 
/NODEBUG None /DEBUG 
/DEBUG Full /TRACE? 
/DEBUG=TRACE Traceback only /TRACE 
/NODEBUG None /TRACE 
/DEBUG Full /NOTRACE 


'See Table 5-1 for additional information. 


Command to 
invoke 
Debugger 


RUN 
RUN 
RUN 


RUN/DEBUG 
RUN/DEBUG 


RUN/DEBUG 


Cannot 


DST Data 
Passed 
to Debugger 


Full 
Traceback only 
None 


Traceback only 
Traceback only 


None 


2LINK/TRACEBACK and LINK/NODEBUG are equivalent. This is the default for the LINK command. 


3A universal symbol is a symbol that is defined in one image and referenced in another. A universal symbol must be defined 
as such at link time. See Section 5.4 for information about universal symbols and shareable images. 


GST Data 
Passed 

to Debugger 
Full 

Full 

Full 


Only universal 
symbols® 


Only universal 
symbols 


Only universal 
symbols 


If you specify /NODEBUG with the compiler command and subsequently 
link and execute the image, the debugger issues the following message 


when it is invoked: 


SDEBUG-I-NOLOCALS, image does not contain local symbols 


The preceding message, which occurs whether you linked with the 
/TRACEBACK or /DEBUG qualifier, indicates that no DST has been 
created for that image. Therefore, you have access only to global symbols 


contained in the GST. 


If you do not specify (DEBUG with the LINK command, the debugger 
issues the following message when it is invoked: 


SDEBUG-I-NOGLOBALS, some or all global symbols not accessible 


The preceding message indicates that the only global symbol information 


available during the debugging session is the following: 


¢ Information about global symbols that is stored in the DST. 


¢ Information about universal symbols that is stored in the GST. 


These concepts are discussed in later sections. In particular, see 
Section 5.4 for additional information related to debugging shareable 


images. 
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5.1.4 Controlling Symbol Information in Debugged Images 


Symbol records occupy space within the executable image. After you have 

debugged your program, you might want to link it again without using the 
/DEBUG qualifier, to make the executable image smaller. This creates an 

image with only traceback data in the DST. 


The command LINK/NOTRACEBACK enables you to secure the contents 
of an image from users after it has been debugged. Use this command 
for images that are to be installed with privileges (see the Guide to VMS 
System Security and the Guide to Setting Up a VMS System). When 

you enter LINK/NOTRACEBACK, no symbolic information (including 
traceback data) is passed to the image. Moreover, the debugger cannot be 
invoked, either by the RUN/DEBUG command, or by a CTRL/Y—DEBUG 


sequence while the program is running. 


5.2 Setting and Canceling Modules 
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You need to set a module if the debugger is unable to locate a symbol that 
you have specified (for example, a variable name X) and issues a message 
as in the following example: 


DBG> EXAMINE X 
%DEBUG-E-NOSYMBOL, symbol ’X’ is not in the symbol table 
DBG> 


This section explains module setting and the conditions under which 
you might need to set or cancel a module, using the SET MODULE and 
CANCEL MODULE commands. 


Complete symbol information is passed from your program’s source code to 
the debugger when you compile and link the program using the (DEBUG 
command qualifier, as explained in Section 5.1. 


When you invoke the debugger, symbol information is contained in the 
DST and GST, within the executable image. The DST contains detailed 
information about local and global symbols. The GST duplicates some of 
the global symbol information contained in the DST. 


To facilitate symbol searches, the debugger loads symbol information from 
the DST and GST into a run-time symbol table (RST), which is structured 
for efficient symbol lookup. Unless symbol information is in the RST, the 
debugger does not recognize or properly interpret the associated symbol. 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of 
program execution. The loading process is called module setting, because 
all symbol information for a given module is loaded into the RST at one 
time. 


At debugger startup, all GST records are loaded into the RST because 
global symbols must be accessible throughout the debugging session. Also, 
the debugger sets the module that contains the main program (the routine 
specified by the image transfer address, where execution is suspended at 
the start of a debugging session). You therefore have access to all global 
symbols and to any local symbols that should be visible within the main 
program. 
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Subsequently, whenever execution of the program is interrupted, the 
debugger sets the module that contains the routine in which execution 
is suspended. This enables you to reference the symbols that should be 
visible at the current PC value (in addition to the global symbols). This 
default mode of operation is called "dynamic mode." 


If you try to reference a symbol that is defined in a module that has not 

been set, the debugger warns you that the symbol is not in the RST. You 
must then use the SET MODULE command to set the module containing 
that symbol explicitly. For example: 


DBG> EXAMINE X 

S$DEBUG-E-NOSYMBOL, symbol ’X’ is not in the symbol table 
DBG> SET MODULE MOD3 

DBG> EXAMINE X 

MOD3\ROUT2\X: 26 

DBG> 


The SHOW MODULE command lists the modules of your program and 
identifies which modules are set. 


When a module is set, the debugger automatically allocates memory 

as needed by the RST. This can eventually slow down the debugger as 
more modules are set. If performance becomes a problem, you can use 
the CANCEL MODULE command to reduce the number of set modules, 
thereby automatically releasing memory. Or you can disable dynamic 
mode by entering the command SET MODE NODYNAMIC. When dynamic 
mode is disabled, the debugger does not set modules automatically. Use 
the SHOW MODE command to determine whether dynamic mode is 
enabled or disabled. 


Section 5.4 explains how to set images and modules when debugging 
shareable images. 


5.3 Resolving Symbol Ambiguities 


Symbol ambiguities can occur when a symbol (for example, a variable 
name X) is defined in more than one routine or other program unit. 


In most cases, the debugger resolves symbol ambiguities automatically, 
using the scope and visibility rules of the currently set language and the 
ordering of routine calls on the call stack, as explained in Section 5.3.1. 


However, in some cases the debugger might respond as follows, when you 
specify a symbol that is defined multiple times: 


e It might not be able to determine the particular declaration of the 
symbol that you intended. For example: 
DBG> EXAMINE X 
%$DEBUG-W-NOUNIQUE, symbol ’X’ is not unique 
DBG> 


e It might reference the declaration that is visible in the current scope, 
not the one you want. | 
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To resolve such problems, you must specify a scope where the debugger 
should search for a particular declaration of the symbol. In the following 
example, the path name COUNTER\X uniquely specifies a particular 
declaration of X: 


DBG> EXAMINE COUNTER\X 
COUNTER\X: 14 
DBG> 


The next sections discuss scope concepts and explain how to resolve symbol 
ambiguities. 


5.3.1 Symbol Lookup Conventions 


This section explains how the debugger searches for symbols, resolving 
most potential symbol ambiguities using the scope and visibility rules 
of the programming language and also its own rules. Section 5.3.2 and 
Section 5.3.3 describe supplementary techniques that you can use when 
necessary. 


You can specify symbols in debugger commands by using either a path 
name or the exact symbol. 


If you use a path name, the debugger looks for the symbol in the scope 
denoted by the path name prefix (see Section 5.3.2). 


If you do not specify a path name prefix, by default, the debugger searches 
the RST as explained in the following paragraphs (you can modify 

this default behavior with the SET SCOPE command, as explained in 
Section 5.3.3). 


First, the debugger looks for symbols in the PC scope (also known as scope 
0), according to the scope and visibility rules of the currently set language. 
This means that, typically, the debugger first looks within the block or 
routine surrounding the current PC value (where execution is currently 
suspended). If the symbol is not found, the debugger searches the nesting 
program unit, then its nesting unit, and so on. The precise manner, which 
depends on the language, ensures that the correct declaration of a symbol 
that is defined multiple times is chosen. 


However, note that you can reference symbols throughout your program, 
not just those that are visible in the PC scope as defined by the language. 
This is necessary so you can set breakpoints in arbitrary areas, examine 
arbitrary variables, and so on. Therefore, if the symbol is not visible in the 
PC scope, the debugger continues searching as follows. 


After the PC scope, the debugger searches the scope of the calling routine 
Gif any), then its caller, and so on. Symbolically, the complete scope search 
list is denoted 0,1,2, ...,n, where 0 denotes the PC scope and n is the 
number of calls on the call stack. Within each scope (call frame), the 
debugger uses the visibility rules of the language to locate a symbol. 


This search list, based on the call stack, enables the debugger to 
differentiate symbols that are defined multiple times in a convenient, 
predictable way. 
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If the symbol is still not found, the debugger searches the rest of the RST— 
that is, the other set modules and the global symbol table (GST). At this 
point the debugger does not attempt to resolve symbol any ambiguities. 
Instead, if more than one occurrence of the symbol is found, the debugger 
issues a message such as the following: 


SDEBUG-W-NOUNIQUE, symbol ’Y’ is not unique 


If you have used a SET SCOPE command to modify the default symbol 
search behavior, you can restore the default behavior with the CANCEL 
SCOPE command. 


5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely 


If the debugger indicates that a symbol reference is "not unique," use 
the SHOW SYMBOL command to obtain all possible path names for that 
symbol, then specify a path name to reference the symbol uniquely. For 
example: 


DBG> EXAMINE COUNT 
SDEBUG-W-NOUNIQUE, symbol ‘COUNT’ is not unique 


DBG> SHOW SYMBOL COUNT 

data MOD7\ROUT3\BLOCK1\COUNT 
data MOD4\ROUT2\COUNT 

routine MOD2\ROUT1\ROUT3\COUNT 


DBG> EXAMINE MOD4\ROUT2\COUNT 
MOD4\ROUT2\COUNT: 12 
DBG> 


The command SHOW SYMBOL COUNT lists all declarations of the 
symbol COUNT that exist in the RST. The first two declarations of 
COUNT are variables (data). The last declaration listed is a routine. 
Each declaration is shown with its path name prefix, which indicates the 
path (search scope) the debugger must follow to reach that particular 
declaration. For example, MOD4\ ROUT2\ COUNT denotes the 
declaration of the symbol COUNT in routine ROUT2 of module MOD4. 


The path name format is as follows. The leftmost element of a path name 
identifies the module containing the symbol. Moving toward the right, the 
path name lists the successively nested routines and blocks that lead to 
the particular declaration of the symbol (which is the rightmost element). 


Although the debugger always displays symbols with their path names, 
you need to use path names in debugger commands only to resolve an 
ambiguity. 


The debugger looks up line numbers like any other symbols you specify 
(by default, it first looks in the module where execution is suspended). A 
common use of path names is for specifying a line number in an arbitrary 
module. For example: 


DBG> SET BREAK QUEUE MANAGER\%LINE 26 
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Note that the SHOW SYMBOL command identifies global symbols twice, 
because global symbols are included both in the DST and in the GST. For 


example: 

DBG> SHOW SYMBOL X 

data. ALPHA\X ! global X 

data ALPHA\BETA\X ! local X 

data X (global) ! same as ALPHA\X 
DBG> 


5.3.2.1. Simplifying Path Names 
Path names are often long. You can simplify the process of specifying path 
names in three ways: 


e Abbreviate a path name. 
¢ Define a brief symbol for a path name. 


¢ Set a new search scope so you do not have to use a path name. 


To abbreviate a path name, delete the names of nesting program units 
starting from the left, leaving enough of the path name to specify it 
uniquely. For example, ROUT3\ COUNT is a valid abbreviated path name 
for the routine in the first example of Section 5.3.2. 


To define a symbol for a path name, use the DEFINE command. For 
example: 


DBG> DEFINE INTX = INT STACK\CHECK\X 
DBG> EXAMINE INTX 


To set a new search scope, use the SET SCOPE command, which is 
described in Section 5.3.3. 


5.3.2.2 Specifying Symbols in Routines on the Call Stack 
You can use a numeric path name to specify the scope associated with a 
routine on the call stack (as identified in a SHOW CALLS display). The 
path name prefix "0\" denotes the PC scope, the path name prefix "1\" 
denotes scope 1 (the scope of the caller routine), and so on. 


For example, the following commands display the current values of 
two distinct declarations of Y, which are visible in scope 0 and scope 2, 
respectively. 


DBG> EXAMINE O\Y 
DBG> EXAMINE 2\Y 


By default, the command EXAMINE Y signifies EXAMINE OVY. 


See also the description of the command SET SCOPE/CURRENT in 
Section 5.3.3. That command enables you to reset the reference for the 
default scope search list relative to the call stack. 


5.3.2.3. Specifying Global Symbols 
To specify a global symbol uniquely, use a backslash (\ ) as a prefix to the 
symbol. For example, the following command displays the value of the 
global symbol X: 


DBG> EXAMINE \X 
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5.3.2.4 Specifying Routine Invocations 
When a routine is called recursively, you might need to distinguish among 
several calls to the same routine, all of which generate new symbols with 
identical names. 


You can include an invocation number in a path name to indicate a 
particular call to a routine. The number must be a nonnegative integer 
and must follow the name of the rightmost routine in the path name. Zero 
denotes the most recent invocation; 1 denotes the previous invocation, 
and so on. For example, if PROG calls COMPUTE and COMPUTE 

calls itself recursively, and each call creates a new variable SUM, the 
following command displays the value of SUM for the most recent call to 
COMPUTE: 


DBG> EXAMINE PROG\COMPUTE 0\SUM 


To refer to the variable SUM that was generated in the previous call to 
COMPUTE, you would express the path name with a 1 in place of the 0. 


When you do not include an invocation number, the debugger assumes 
that the reference is to the most recent call to the routine (the default 
invocation number is 0). 


See also the description of the command SET SCOPE/CURRENT in 
Section 5.3.3. That command enables you to reset the reference for the 
default scope search list relative to the call stack. 


9.3.3 Using SET SCOPE to Specify a Symbol Search Scope 


By default, the debugger looks up symbols that you specify without a path 
name prefix by using the scope search list described in Section 5.3.1. 


The SET SCOPE command enables you to establish a new scope for symbol 
lookup, so that you do not have to use a path name when referencing 
symbols in that scope. 


In the following example, the SET SCOPE command establishes the 
path name MOD4\ ROUT2 as the new scope for symbol lookup. Then, 
references to Y without a path name prefix specify the declaration of Y 
that is visible in the new scope. | 


DBG> EXAMINE Y 

S%DEBUG~E-NOUNIQUE, symbol ’Y’ is not unique 
DBG> SHOW SYMBOL Y 

data MOD7\ROUT3\BLOCK1\Y 

data MOD4\ROUT2\Y 


DBG> SET SCOPE MOD4\ROUT2 
DBG> EXAMINE Y 
MOD4\ROUT2\Y: 12 

DBG> 


After you have entered a SET SCOPE command, the debugger applies the 
path name you specified in the command to all references that are not 
individually qualified with path names. 
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You can specify numeric path names with SET SCOPE (see 
Section 5.3.2.2). For example, the following command sets the current 
scope to be three calls down from the PC scope. 


DBG> SET SCOPE 3 


You can also define a scope search list to specify the order in which the 
debugger should search for symbols. For example, the following command 
causes the debugger to look for symbols first in the PC scope (scope 0) and 
then in the scope denoted by routine ROUT2 of module MOD4: 


DBG> SET SCOPE 0, MOD4\ROUT2 


The debugger’s default scope search list is equivalent to entering the 
following command (if it existed): 


DBG> SET SCOPE 0,1,2,3,... 7M 


Here the debugger searches successively down the call stack to find a 
symbol. 


You can use the command SET SCOPE/CURRENT to reset the reference 
for the default scope search list to another routine down the call stack. 


For example, the following command sets the scope search list to be 
2,3,4, ... 42: 


DBG> SET SCOPE/CURRENT 2 


To display the current scope search list for symbol lookup, use the 
SHOW SCOPE command. To restore the default scope search list (see 
Section 5.3.1), use the CANCEL SCOPE command. 


5.4 Debugging Shareable Images 


By default, your program might be linked with several Digital-supplied 
shareable images (for example, the run-time library image MTHRTL.EXE). 
This section explains how to extend the concepts described in the previous 
sections when debugging user-defined shareable images. 


A shareable image is not intended to be directly executed. A shareable 
image must first be included as input in the linking of an executable 
image, and then the shareable image is loaded at run time when the 
executable image is run. You do not have to install a shareable image to 
debug it. Instead, you can debug your own private copy by assigning a 
logical name to it. 


See the VMS Linker Utility Manual for detailed information about linking 
shareable images. 


5.4.1. Compiling and Linking Shareable Images for Debugging 


The basic steps in compiling and linking a shareable image for debugging 
are as follows (an example follows the steps): 


1 Compile the source files for the main image and for the shareable 
image, using the /DEBUG qualifier. 
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2 Link the shareable image with the /SHAREABLE and /DEBUG 
command qualifiers, declaring any universal symbols for that image 
using the UNIVERSAL linker option. (A universal symbol is a symbol, 
for example a routine name, that is defined in a shareable image and 
referenced in another image.) 


3 Link the shareable image against the main image, specifying the 
shareable image with the /SHAREABLE file qualifier as a linker 
option. Also specify the /DEBUG command qualifier. 


4 Define a logical name to point to the local copy of the shareable 
image. You must specify the device and directory as well as the 
image name. Otherwise the VMS image activator looks for an 
image of that name in the system default shareable image library 
(SYS$LIBRARY:IMAGELIB.OLB). 


5 Execute the main image to invoke the debugger. The shareable image 
is loaded at run time. 


These steps are illustrated next with a simple example. In the example, 
MAIN.FOR and SUB1.FOR are the source files for the main image (the 
executable image that you specify with the RUN command); SHR1.FOR 
and SHR2.FOR are the source files for the shareable image to be 
debugged. 


You compile the source files for each image as described in Section 5.1: 


$ FORTRAN/NOOPT/DEBUG MAIN, SUB1 
$ FORTRAN/NOOPT/DEBUG SHR1,SHR2 


You then use the LINK command to create the shareable image, also 
specifying any universal symbols: 
$ LINK/SHAREABLE/DEBUG SHR1,SHR2,SYSSINPUT:/OPTIONS 


UNIVERSAL=SHR_ ROUT 
S) 


In the preceding example, . 


¢ The /SHAREABLE command qualifier creates the shareable image 
SHR1.EXE from the object files SHR1.OBJ and SHR2.OBJ. 


¢ The /OPTIONS qualifier appended to SYS$INPUT: enables you 
to specify the global symbol SHR_ROUT as a universal symbol 
interactively. | 


¢ The /DEBUG command qualifier builds a DST and a GST for 
SHR1.EXE and puts them in that image. The GST contains the 
universal symbol SHR_ROUT. Note that the linker puts universal 
symbols in the GST unless you specify LINK/NOTRACEBACK, 
because universal symbols must be global symbols as well. 


You have now built the shareable image SHR1.EXE in your current default 
directory. Because SHR1.EXE is a shareable image, you do not execute it — 
directly with the RUN command. Instead you link SHR1.EXE against the 
main (executable) image: : 


$ LINK/DEBUG MAIN, SUB1,SYSSINPUT: /OPTION 
SHR1.EXE/SHAREABLE 
$ 
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In the preceding example, 


e The LINK command creates the executable image MAIN.EXE from 
MAIN.OBJ and SUB1.OBJ. 


¢ The /DEBUG qualifier builds a DST and a GST for MAIN.EXE and 
puts them in that image. 


¢ The /SHAREABLE qualifier appended to SHR1.EXE specifies that 
SHR1.EXE is to be linked against MAIN.EXE as a shareable image. 


When you execute the resulting main image, MAIN.EXE, any shareable 
images linked against it are loaded at run time. However, by default the 
VMS image activator looks for shareable images in the system default 
shareable image library (SYS$LIBRARY:IMAGELIB.OLB). Therefore, you 
must define the logical name SHR1 to point to SHR1.EXE in your current 
default directory. Be sure to specify the device and directory: 


$ DEFINE SHR1 SYSSDISK: []SHR1.EXE 


You can now invoke the debugger to debug both MAIN and SHR1 by 
entering the following command: 


$ RUN MAIN 


5.4.2 Accessing Symbols in Shareable Images 


All the concepts covered in Section 5.1, Section 5.2, and Section 5.3 apply 
to the modules of a single image, namely the main (executable) image. 
This section provides additional information that is specific to debugging 
shareable images. 


When you link shareable images for debugging as explained in 
Section 5.4.1, the linker builds a DST and a GST for each image. To 
conserve memory, the debugger builds an RST for an image only when 


that image is "set," either dynamically by the debugger or when you enter 
a SET IMAGE command. 


The SHOW IMAGE command identifies all shareable images that are 
linked with your program, shows which images are set, and identifies the 
current image (see Section 5.4.2.2 for a definition of the current image). 
Only the main image is set initially when you invoke the debugger. 


The following sections explain how the debugger sets images dynamically 
during program execution and how you can access symbols in arbitrary 
images independently of execution. | 


Refer also to Section 3.6.2.4 for information about setting watchpoints in 
installed writeable shareable images. 


5.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode) 
By default, dynamic mode is enabled. Therefore, whenever the debugger 
interrupts execution, the debugger sets the image and module where 
execution is suspended, if they are not already set (unless the image was 
linked with the /NOTRACEBACK qualifier). 
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Dynamic mode gives you the following access to symbols automatically: 


¢ You can reference symbols defined in all set modules in the image 
where execution 1s suspended. 


e You can reference symbols in the GST for that image, including any 
universal symbols defined for that image. 


e By setting other modules in that image, you can reference any symbol 
defined in the image. 


After an image is set, it remains set until you cancel it with the CANCEL 
IMAGE command. If the debugger slows down as more images and 
modules are set, use the CANCEL IMAGE command. You can also enter 
the command SET MODE NODYNAMIC to disable dynamic mode. 


5.4.2.2 Accessing Symbols in Arbitrary Images 
The last image that you or the debugger sets is the current image. The 
current image is the debugging context for symbol lookup. Therefore, 
when using the following commands, you can reference only the symbols 
that are defined in the current image: 


e (SET, SHOW, CANCEL) MODULE 

e SHOW SYMBOL 

e EXAMINE, DEPOSIT, EVALUATE 

e TYPE 

e (SET, CANCEL) BREAK 

¢ (SET, CANCEL) TRACE 

e (SET, CANCEL) WATCH 

e DEFINE/ADDRESS, DEFINE/VALUE 

However, note that the commands SHOW BREAK, SHOW TRACEH, and 


SHOW WATCH identify any breakpoints, tracepoints, or watchpoints that 
have been set in all images. 


To reference a symbol in another image, use the SET IMAGE command to 
make the specified image the current image, then use the SET MODULE 
command to set the module where that symbol is defined (the SET IMAGE 
command does not set any modules). The following example illustrates 
these concepts. 


The sample program consists of a main image PROGI and a shareable 
image SHR1. Assume that you have just invoked the debugger and that 
execution is suspended in image PROGI1, within the main program. Now, 
suppose you want to set a breakpoint on routine ROUT2, which is defined 
in some module in image SHR1. 


If you try to set a breakpoint on ROUT2, the debugger looks for ROUT2 in 
the current image, PROGI: 


DBG> SET BREAK ROUT2 


S$DEBUG-E-NOSYMBOL, symbol ‘’ROUT2’ is not in symbol table 
DBG> 
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The SHOW IMAGE command shows that image SHR1 needs to be set: 


DBG> SHOW IMAGE 


image name set base address end address 
*PROG1 yes 00000200 00000 9FF 
SHR1 no 00001000 QOOOOLFFF 
total images: 2 bytes allocated: 32856 


DBG> SET IMAGE SHR1 
DBG> SHOW IMAGE 


image name set base address end address 
PROG1 yes 00000200 OO0009FF 
*SHR1 yes 00001000 OOOOLFFF 
total images: 2 bytes allocated: 41948 

DBG> 


SHRI is now set and is the current image. However, because the SET 
IMAGE command does not set any modules, you must set the module 
where ROUT2 is defined before you can set the breakpoint: 


DBG> SET BREAK ROUT2 
S$DEBUG-E-NOSYMBOL, symbol ‘’ROUT2’ is not in symbol table 
DBG> SET MODULE/ALL 
DBG> SET BREAK ROUT2 


DBG> GO 

break at routine ROUT2 

LOS SUBROUTINE ROUT2 (A,B) 
DBG> 


Now that you have set image SHR1 and all its modules and have reached 
the breakpoint at ROUT2, you can debug using the normal method (for 
example, step through the routine, examine variables, and so on). 


After you have set an image and set modules within that image, the 
image and modules remain set even if you establish a new current image. 
However, you have access to symbols only in the current image at any one 
time. 


5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images 


The following paragraphs describe how to access a universal symbol (such 
as a routine name) in a run-time library or other shareable image for 
which no symbol-table information was generated. With this information 
you can, for example, use the CALL command to execute a run-time 
library or system-service routine as explained in Section 8.7. 


If no symbol-table information was generated for a shareable image, 
you cannot set the image with the SET IMAGE command. For example, 
suppose you want to set image LIBRTL, which is linked with program 
EIGHTQUEENS: 


DBG> SHOW IMAGE 


image name set base address end address 
*RIGHTQUEENS yes 00000200 OOO0009FF 
DBGSSISHR no 00075000 000783FF 
DEBUG no 00022200 O0074FFF 
LIBRTL no OOOO0A00 OOOLO9OFF 
PASRTL no 00019A00 O00221FF 
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total images: 5 bytes allocated: 108560 

DBG> SET IMAGE LIBRTL 

SDEBUG-I-UNASETIMG, unable to set image LIBRTL because 
it has no symbol table 


To set the image in such cases, use the SET MODULE command with the 
following command syntax: 


SET MODULE SHARE$image-name 
For example: 


DBG> SET MODULE SHARESLIBRTL 


The debugger creates dummy modules for each shareable image in your 
program. The names of these shareable "image modules" have the prefix 
"SHARE$". The command SHOW MODULE/SHARE identifies these 
shareable image modules, as well as the modules in the current image. 


Once a shareable image module has been set with the SET MODULE 
command, you can access all of its universal symbols. For example, the 
following command lists all of the universal symbols in LIBRTL: 


DBG> SHOW SYMBOL * IN SHARESLIBRTL 


routine SHARESLIBRTL\STRSAPPEND 
routine SHARESLIBRTL\STRSDIVIDE 
routine SHARESLIBRTL\STRSROUND 


routine SHARESLIBRTL\LIBSWAIT 
routine SHARESLIBRTL\LIBSGETDVI 


You can then specify these universal symbols with, for example, the CALL 
or SET BREAK command. 


Setting a shareable image module with the SET MODULE command loads 
the universal symbols for that image into the run-time symbol table so 
that you can reference these symbols from the current image. However, 
you cannot reference other (local or global) symbols in that image from the 
current image. That is, your debugging context remains set to the current 
image. ° 
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6 Controlling the Display of Source Code 


The term source code refers to statements in a programming language as 
they appear in a source file. Each line of source code is also called a source 
line. 


This chapter covers the following topics: 


¢ How the debugger obtains information about source files and source 
lines. 


e Specifying the location of a source file that has been moved to another 
directory after it was compiled. 


e Displaying source lines by specifying line numbers, code address 
expressions, or search strings. 


¢ Controlling the display of source code at breakpoints, tracepoints, and 
watchpoints and after a STEP command has been executed. 


e Using the SET MARGINS command to improve the display of source 
lines under certain circumstances. 


The techniques described in this chapter apply to screen mode as well as 
line (noscreen) mode. Any difference in behavior between line mode and 
screen mode is identified in this chapter and in the command dictionary 
for the commands discussed. (Screen mode is described fully 1n Chapter 7.) 


If your program has been optimized by the compiler, the code that is 
executing as you debug might not always match your source code. See 
Section 9.1 for information about that subject. 


6.1 How the Debugger Obtains Source Code Information 


When a compiler processes source files to generate object modules, 

it assigns a line number to each source line sequentially. For most 
languages, each compilation unit (module) starts with line 1. For others 
like Ada, each source file, which might represent several compilation units, 
starts with line 1. 


Line numbers appear in a source listing obtained with the /LIST compile- 
command qualifier. They also appear whenever the debugger displays 
source code, either in line mode or screen mode. Moreover, you can specify 
line numbers with several debugger commands (for example, TYPE, SET 
BREAK). 


The debugger displays source lines only if you have specified the /DEBUG 
command with both the compile command and the LINK command. Under 
these conditions, the symbol information created by the compiler and 
passed to the debug symbol table (DST) includes source-line correlation 
records. For a given module, source-line correlation records contain the 
full VMS file specification of each source file that contributes to that 
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module. In addition, they associate source records (symbols, types, and so 
on) with source files and line numbers in the module. 


Specifying the Location of Source Files 


The debug symbol table (DST) contains the full VMS file specification of 
each source file when it was compiled. Thus, by default, the debugger 
expects a source file to be in the same directory it was in at compile time. 
If a source file is moved to a different directory after it is compiled, the 
debugger does not find it and displays a warning such as the following 
when attempting to display source code from that file: 


%SDEBUG-W-UNAOPNSRC, unable to open source file DISK: [JONES.WORK] PRG.FOR; 2 
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In such cases, use the SET SOURCE command to direct the debugger to 
the new directory. The command can be applied to all source files for your 
program or to only the source files for specific modules. 


For example, after the following command line is entered, the debugger 
looks for all source files in WORK$:[JONES.PROG3]: 


DBG> SET SOURCE WORKS: [JONES.PROG3] 


You can specify a directory search list with the SET SOURCE command. 
For example, after the following command line is entered, the debugger 


looks for source files first in the current default directory ([]) and then in 
WORK$:[JONES.PROG3]: 


DBG> SET SOURCE [], WORKS: [JONES.PROG3] 


If you want to apply the SET SOURCE command only to the source 

files for a given module, use the (MODULE=module-name qualifier 

and specify that module. For example, the following command line 
specifies that the source files for module SCREEN_IO are in the directory 
DISK2:[SMITH.SHARE] (the search of source files for other modules is not 
affected by this command): 


DBG> SET SOURCE/MODULE=SCREEN IO DISK2: [SMITH. SHARE] 


In summary, the SET SOURCE/MODULE command specifies the location 
of source files for a particular module, whereas the SET SOURCE 
command specifies the location of source files for modules that were 

not mentioned explicitly in SET SOURCE/MODULE commands. 


Use the SHOW SOURCE command to display all source directory search 
lists currently in effect. The command displays the search lists for 
specific modules (as previously established by one or more SET SOURCE 
/MODULE commands) and the search list for all other modules (as 
previously established by a SET SOURCE command). For example: 
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DBG> SET SOURCE [PROJA], [PROJB],USERS: [PETER.PROJC] 
DBG> SET SOURCE/MODULE=COBOLTEST [], DISKS$2: [PROJD] 
DBG> SHOW SOURCE 


source directory search list for COBOLTEST: 
[] 
DISK$2: [PROJD] 
source directory search list for all other modules: 
[PROJA] 
[PROJB] 
USERS: [PETER.PROJC] 
DBG> 


If no SET SOURCE or SET SOURCE/MODULE command has been 
entered, the SHOW SOURCE command indicates that no search list is 
currently in effect. 


Use the CANCEL SOURCE command to cancel the effect of a previous 
SET SOURCE command. Use the CANCEL SOURCE/MODULE command 
to cancel the effect of a previous SET SOURCE/MODULE command 
(specifying the same module name). 


When a source directory search list has been canceled, the debugger again 
expects the source files corresponding to the designated modules to be in 
the same directories they were in at compile time. 


See the description of the SET SOURCE command in the command 
dictionary for additional information about how the debugger locates 
source files that have been moved to another directory after compile time. 


Opening a source file requires the use of an I/O channel, a limited system 
resource. Like the debugger, your program might need to open files. To 
ensure that the debugger does not use all available I/O channels and thus 
cause the program to fail, by default the debugger can keep a maximum 
of 5 source files open at one time. To specify a different limit, use the SET 
MAX SOURCE_FILES command. For example, the following command 
line sets the limit to 7 source files: 


DBG> SET MAXIMUM SOURCE FILES 7 


Note that the value specified limits only the number of source files that 
can be kept open at any one time. If the debugger reaches this limit, 

it closes a file in order to open another one. Note also that setting the 
limit to a very small number can make the debugger’s use of source files 
inefficient. 


The SHOW MAX SOURCE_FILES command displays the number of 
source files that the debugger can keep open at one time. 


6.3 Displaying Source Code by Specifying Line Numbers 


The TYPE command enables you to display source lines by specifying 
compiler-assigned line numbers, where each line number designates a line 
of source code. 
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For example, the following command displays line 160 and lines 22 to 24 
of the module being debugged: 


DBG> TYPE 160, 22:24 
module COBOLTEST 

160: START-IT-PARA. 
module COBOLTEST 


22: Q2 SC2V2 PIC S99V99 COMP VALUE 22.33. 

235% -O2 SC2V2N PIC S99V99 COMP VALUE -22.33. 

24: Q2 CPP2 PTC PP9Y COMP VALUE 0.0012. 
DBG> 


You can display all the source lines of a module by specifying a range of 
line numbers starting from 1 and ending at a number equal to or greater 
than the largest line number in the module. 


After displaying a source line, you can display the next line in that module 
by entering a TYPE command without a line number—that is, by entering 
a TYPE command and then pressing the Return key. For example: 


DBG> TYPE i160 
module COBOLTEST 
160: START-IT-PARA. 
DBG> TYPE 
module COBOLTEST 
LO1: MOVE SC1 TO ESO. 
DBG> 


You can then display the next line and successive lines by entering the 
TYPE command repeatedly, in this way reading through your code one line 
at a time. 


To display source lines in an arbitrary module of your program, specify the 
module name with the line numbers. Use standard path name notation— 
that is, first specify the module name, then a backslash (\ ), and finally 
the line numbers (or the range of line numbers), without intervening 
spaces. For example, the following command displays line 16 of module 
TEST: 


DBG> TYPE TEST\16 


If you specify a module name with the TYPE command, the module 
must be set. Use the SHOW MODULE command to determine whether 
a particular module is set. Then use the SET MODULE command, if 
necessary (see Section 5.2). 


If you do not specify a module name with the TYPE command, the 
debugger displays source lines for the module in which execution is 
currently suspended, by default—that is, the module associated with 

the PC scope. If you have specified another scope with the SET SCOPE 
command the debugger displays source lines in the module associated with 
the specified scope. 


In screen mode, the output of a TYPE command updates the current 
source display (see Section 7.6.6). 


After displaying source lines at various locations in your program, you can 
redisplay the line at which execution is currently suspended by pressing 
keypad key 5. 


Controlling the Display of Source Code 
6.4 Displaying Source Code by Specifying Code Address Expressions 


6.4 Displaying Source Code by Specifying Code Address Expressions 


The EXAMINE/SOURCE command enables you to display the source line 
corresponding to a code address expression. A code address expression 
denotes the address of a machine code instruction and, therefore, must be 
one of the following: 


e A line number associated with one or more instructions 
e 6A label 
e A routine name 


e The memory address of an instruction 


You cannot specify a variable name with the EXAMINE/SOURCE 
command, because a variable name is associated with data, not with 
instructions. 


When you use the EXAMINE/SOURCE command, the debugger evaluates 
the address expression to obtain a memory address, determines which 
compiler-assigned line number corresponds to that address, and then 
displays the source line designated by the line number. 


For example, the following command line displays the source line 
associated with the address (declaration) of routine SWAP: 


DBG> EXAMINE/SOURCE SWAP 
module MAIN 

47: procedure SWAP (X,Y: in out INTEGER) is 
DBG> 


If you specify a line number that is not associated with an instruction, the 
debugger issues a diagnostic message. For example: 


DBG> EXAMINE/SOURCE %LINE 6 

SDEBUG~I-LINEINFO, no line 6, previous line is 5, next line is 8 
%DEBUG-E-NOSYMBOL, symbol ’/SLINE 6’ is not in the symbol table 
DBG> 


When using the EXAMINE/SOURCE command, with a symbolic address 
expression (a line number, label, or routine), you might need to set the 
module in which the entity is defined, unless that module is already set. 
Use the SHOW MODULE command to determine whether a particular 
module is set. Then use the SET MODULE command, if necessary (see 
Section 5.2). 


The command EXAMINE/SOURCE .%PC displays the source line 
corresponding to the current PC value (the line that is about to be 
executed). For example: 


DBG> EXAMINE/SOURCE .%PC 
module COBOLTEST 

162: DISPLAY ESO. 
DBG> 


Note the use of the "contents-of" operator (.), which specifies the contents 
of the entity that follows the period. If you do not use the contents-of 
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operator, the debugger tries to find a source line for the PC rather than for 
the address currently stored in the PC: 


DBG> EXAMINE/SOURCE %PC 
!$DEBUG-W-NOSRCLIN, no source line for address 7FFFOO5C 
DBG> 


The following example shows the use of a numeric path name (1\) to 
display the source line at the PC value one level down the call stack (at 
the call to the routine in which execution is suspended): 


DBG> EXAMINE/SOURCE .1\%PC 


In screen mode, the output of an EXAMINE/SOURCE command updates 
the current source display (see Section 7.6.6). 


The debugger uses the EXAMINE/SOURCE command in the following 
contexts to display source code at the current PC value. 


Keypad key 5 is bound to the following debugger command sequence: 
EXAM/SOURCE .%SOURCE_SCOPE\%PC; EXAM/INST .%INST_SCOPE\%PC 


This command sequence displays the source line and the instruction 

at which execution is currently suspended in the current scope. Thus, 
pressing keypad key 5 enables you to quickly determine your debugging 
context. 


The predefined source display SRC is an automatically updated display 
that executes the following built-in command every time the debugger 

interrupts execution and prompts for commands (see Section 7.2.1 and 
Section C.3.1): 


EXAMINE/SOURCE .%SOURCE_SCOPE\%PC 


6.5 Displaying Source Code by Searching for Strings 
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The SEARCH command enables you to display any source lines that 
contain an occurrence of a specified string. 


The syntax of the SEARCH command is as follows: 
SEARCH([/qualifier[, ... J] [range] [string] 


The range parameter can be a module name, a range of line numbers, or 
a combination of both. If you do not specify a module name, the debugger 
uses the current scope to find source lines, as with the TYPE command 
(see Section 6.3). 


By default, the SEARCH command displays the source line that contains 
the first (next) occurrence of a string in a specified range (SEARCH 
/NEXT). The command SEARCH/ALL displays all source lines that contain 
an occurrence of a string in a specified range. For example, the following 
command line displays the source line that contains the first occurrence of 
the string "pro" in module SCREEN_IO: 


DBG> SEARCH SCREEN IO pro 


The remaining examples use source lines from one COBOL module, in the 
current scope, to illustrate various aspects of the SEARCH command. 
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The following command line displays all source lines within lines 40 to 50 
that contain an occurrence of the string "D". 


DBG> SEARCH/ALL 40:50 D 
module COBOLTEST 


40: 02 D2N COMP-2 VALUE -234560000000. 

423-02 D COMP-2 VALUE 222222.33. 

42: 02 DN COMP-2 VALUE -222222.333333. 

47: 02 DRO COMP-2 VALUE 0.1. 

48: 02 DRS COMP-2 VALUE 0.000001. 

49: 02 DR1O COMP-2 VALUE 0.00000000001. 

50: O2 DR15 COMP-2 VALUE 0.0000000000000001. 
DBG> 


After you have found an occurrence of a string in a particular module, you 
can enter the SEARCH command with no parameters to display the source 
line containing the next occurrence of the same string in the same module. 
This is analogous to using the TYPE command without a parameter to 
display the next source line. For example: 


DBG> SEARCH 42:50 D 
module COBOLTEST 
42: Q2 DN COMP-2 VALUE ~-222222 333333. 
DBG> SEARCH 
module COBOLTEST 
47: O02 DRO COMP-2 VALUE 0.1. 
DBG> 


By default, the debugger searches for a string as specified and does not 
interpret the context surrounding an occurrence of the string (this is 
the behavior of SEARCH/STRING). If you want to locate occurrences of 
a string that is an identifier in your program (for example, a variable 
name) and exclude other occurrences of the string, use the IDENTIFIER 
qualifier. The command SEARCH/IDENTIFIER displays only those 
occurrences of the string that are bounded on either side by a character 
that cannot be part of an identifier in the current language. 


The default qualifiers for the SEARCH command are /NEXT and /STRING. 
If you want to establish different default qualifiers, use the SET SEARCH 
command. For example, after the following command is executed, the 
SEARCH command behaves like SEARCH/IDENTIFIER: 


DBG> SET SEARCH IDENTIFIER 


Use the SHOW SEARCH command to display the default qualifiers 
currently in effect for the SEARCH command. For example: 


DBG> SHOW SEARCH 
search settings: search for next occurrence, as an identifier 
DBG> 


6.6 Controlling Source Display After Stepping and at Event Points 


By default, the debugger displays the associated source line when a 
breakpoint, tracepoint, or watchpoint is triggered and upon the completion 
of a STEP command. | 
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When you enter a STEP command, the debugger displays the source line 
at which execution is suspended after the step. For example: 


DBG> STEP 
stepped to MAIN\SLINE 16 

16: RANGE := 500; 
DBG> 


When a breakpoint or tracepoint is triggered, the debugger displays the 
source line at the breakpoint or tracepoint, respectively. For example: 


DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 
47: procedure SWAP (X,Y: in out INTEGER) is 
DBG> 


When a watchpoint is triggered, the debugger displays the source 
line corresponding to the instruction that caused the watchpoint to be 
triggered. 


The SET STEP [NO]JSOURCE command enables you to control the 
display of source code after a step and at breakpoints, tracepoints, and 
watchpoints. SET STEP SOURCE, the default, enables source display. 
SET STEP NOSOURCE suppresses source display. For example: 


DBG> SET STEP NOSOURCE 
DBG> STEP 

stepped to MAIN\SLINE 16 
DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 
DBG> 


You can selectively override the effect of a SET STEP SOURCE command 
or a SET STEP NOSOURCE command by using the qualifiers /SOURCE 
and /NOSOURCE with the STEP, SET BREAK, SET TRACE, and SET 
WATCH commands. 


The command STEP/SOURCE overrides the effect of the command SET 
STEP NOSOURCE, but only for the duration of that STEP command 
(similarly, STEP/NOSOURCE overrides the effect of SET STEP SOURCE 
for the duration of that STEP command). For example: 


DBG> SET STEP NOSOURCE 
DBG> STEP/SOURCE 
stepped to MAIN\%SLINE 16 
16: RANGE := 500; 
DBG> 


The command SET BREAK/SOURCE overrides the effect of the command 
SET STEP NOSOURCE, but only for the breakpoint set with that SET 
BREAK command (similarly, SET BREAK/NOSOURCE overrides the 
effect of SET STEP SOURCE for the breakpoint set with that SET 
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BREAK command). The same conventions apply to the SET TRACE 
and SET WATCH commands. For example: 


DBG> SET STEP SOURCE 
DBG> SET BREAK/NOSOURCE SWAP 
DBG> GO 


break at MAIN\SWAP 
DBG> 


6.7 Setting Margins for Source Display 


The SET MARGINS command enables you to specify the leftmost and 
rightmost source-line character positions at which to begin and end the 
display of a source line (respectively, the left and right margins). This is 
useful for controlling the display of source code when, for example, the 
code is deeply indented or long lines wrap at the right margin. In such 
cases, you can set the left margin to eliminate indented space in the source 
display, and you can decrease the right margin setting to truncate lines 
and prevent them from wrapping. 


For example, the following command line sets the left margin to column 
20 and the right margin to column 35. 


DBG> SET MARGINS 20:35 


Subsequently, only that portion of the source code that is between columns 
20 and 35 is displayed when you enter commands that display source 
lines (for example, TYPE, SEARCH, STEP). Use the SHOW MARGINS 
command to identify the current margin settings for the display of source 
lines. 


Note that the SET MARGINS command affects only the display of source 
lines. It does not affect the display of other debugger output, as from an 
EXAMINE command. 


The SET MARGINS command is useful mostly in line (noscreen) mode. In 
screen mode, the SET MARGINS command has no effect on the display of 
source lines in a source display, such as the predefined display SRC. 
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7 Using Screen Mode 


Screen mode enables you to see more information more conveniently than 
the default, line-oriented, display mode. In screen mode, you display 
different types of data in separate areas of the screen. You might, for 
example, display your source code in the top left half of the screen, the 
contents of the VAX registers in the top right half, debugger output in 
the middle, and diagnostic messages at the bottom, near your interactive 
input. 


To enable screen mode, press keypad key PFS (or type the command SET 
MODE SCREEN). To return to line-oriented debugging, press GOLD- 
PF3 (or type the command SET MODE NOSCREEN). In screen mode, 

to re-create the default layout of various windows, press the keypad-key 
sequence BLUE-MINUS (PF4 followed by the MINUS key (—)). 


Screen mode output is best displayed on VT100-, VT200-, or VT300- 
series terminals and workstations running VWS. The larger screen of 
workstations is particularly suitable to using a number of displays for 
different purposes. You can use screen mode with VT52 terminals, but 
they are less suited to the formatted screen displays because they do not 
support the scrolling regions used in screen mode. 


This chapter covers the following topics: 
e Screen mode concepts and terminology used throughout the chapter. 


¢ The predefined displays SRC, OUT, PROMPT, INST, and REG, which 
are automatically available when you enter screen mode. 


e Scrolling, hiding, deleting, moving, and resizing a display. 
e Creating a new display. 

e Specifying a display window. 

e The different kinds of displays and how to use them. 


e Directing various types of debugger output to different displays by 
assigning display attributes. 


¢ A sample display configuration that illustrates a possible use of screen 
mode. 


e Saving the current state of your screen displays. 


¢ Changing your terminal screen’s height and width during a debugging 
session and the effect on display windows. 


Many screen mode commands are bound to keypad keys. See Appendix B 
for key definitions. Also, Appendix C contains screen mode information in 
summary reference format. 
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Note: This chapter provides information common to programs that 


run in one or several processes. See Chapter 10 for additional 
information specific to multiprocess programs. 


Concepts and Terminology 


A display is a group of text lines. The text might be lines from a source 
file, assembly language instructions, the values contained in registers, 
your input to the debugger, various types of debugger output, or program 
input and output. 


You view a display through its window, which can occupy any rectangular 
area of the screen. Because a display’s window is typically smaller than 
the display, you can scroll the window up, down, right, and left across the 
display text to view any part of the display. 


Figure 7—1 is an example of screen mode that shows three displays. The 
name of each display (SRC, OUT, and PROMPT) appears at the top left 
corner of its window. It serves both as a tag on the display itself and as a 
name for future reference in commands. : 


Figure 7-1 Default Screen Mode Display Configuration 









— SRC: module SQUARESSMAIN — scroll-source 
















tea © -- Square all non-zero elements and store in output array 
8: K = 0 
oes DO 10 IT=1, N 
10: IF (INARR (I) -NE. 0) THEN 
~> 11: OUTARR (K) = INARR(I) **2 
IZ: ENDIF 


10 CONTINUE 





~~ Print the squared output values. 
PRINT 20, 


17: 20 FORMAT (’ Number of non-zero elements is’ ,I4) 
— OUT-output 
stepped to SQUARESSMAIN\SLINE 9 
a: DO 10 T= 1, N 
SQUARESSMAIN\N: 
SQUARESSMAIN\K: 
stepped to SOUARES$MAIN\ LINE 11 


Then stop. 


~- PROMPT Pa a a 
DBG> EXAM N 

DBG> STEP 2’ 

DGB> 


ZK-6503-GE 
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¢ Display SRC is a source code display (it is displaying FORTRAN code 
in the example shown in Figure 7-1). SRC’s current window is the 
upper half of the screen. Like other display windows, SRC’s window 
can be changed to accommodate different display layouts. The name 
of the module whose source code is displayed, SQUARES$MAIN, is to 
the right of the display name. 
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e Display OUT, located in a window directly below SRC, shows the 
output of debugger commands. 


¢ Display PROMPT, at the bottom of the screen, shows the debugger 
prompt and debugger input. 


Figure 7—1 is the default display configuration that is established when 
you first invoke screen mode. SRC, OUT, and PROMPT are three of the 
five predefined displays that the debugger provides by default when you 
enter screen mode (see Section 7.2). You can create additional displays. 


Every display has a memory buffer, whose size is independent of the 
window size and can be adjusted. Displays that hold source code or 
assembly language instructions enable you to see all of the lines of source 
code of the associated module or all of the instructions of the associated 
routine, regardless of the size of the memory buffer. This is because 

the necessary information is paged into the buffer as needed. For other 
displays, such as display OUT, the buffer size defines how much text the 
display can hold. If you add more text to the display, the oldest text lines 
are discarded to make room for the new text. 


Conceptually, displays are placed on the screen as on a pasteboard. The 
display that is most recently referenced in a command is put on top of the 
pasteboard by default. Therefore, depending on the window locations, the 
displays that you have referenced recently might overlay or hide other 
displays (as on a pasteboard). 


The debugger maintains a display list, which is the pasting order of 
displays. Several keypad key definitions use the display list to cycle 
through the displays currently on the pasteboard. 


Every display belongs to a display kind (see Section 7.6). The display kind 
determines what type of information the display can capture and display; 
for example, source code, assembly language instructions, debugger output 
of various types. The display kind also determines how the contents of the 
display are generated. 


The contents of a display are generated in two ways. Some displays are 
automatically updated. Their definition includes a command list that is 
executed whenever the debugger gains control from the program. The 
output of the command list forms the contents of those displays. Display 
SRC belongs to that category: it is automatically updated so that an 
arrow centered in the window shows the source line at which execution is 
currently suspended. 


Other displays, for example display OUT, derive their contents from 
commands you enter interactively. If you create a display of this general 
category, you must first select it (with the SELECT command) as the 
target display for one or more types of output before anything can be 
written to it. This is also known as assigning one or more attributes to a 
display (see Section 7.7). 


The names of any attributes assigned to a display appear to the right of 
the display name, in lowercase letters. In Figure 7-1 SRC has the source 
and scroll attributes (SRC is the current source display and the current 
scrolling display), OUT has the output attribute (it is the current output 
display), and so on. Note that, although SRC is automatically updated 
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by its own built-in command, it can also receive the output of certain 
interactive commands (such as EXAMINE/SOURCE) because it has the 
source attribute. 


The concepts introduced in this section are developed in more detail in the 
rest of this chapter. 


7.2 Debugger Predefined Displays 


The debugger provides the following predefined displays that you can use 
to capture and display different kinds of data: 


SRC, the predefined source display 
OUT, the predefined output display 
PROMPT, the predefined prompt display 
INST, the predefined instruction display 
REG, the predefined register display 


When you enter screen mode, the debugger puts SRC in the top half of 
the screen, PROMPT in the bottom sixth, and OUT between SRC and 
PROMPT, as illustrated in Figure 7-1. Displays INST and REG are 
initially removed from the screen by default. 


If, after rearranging displays and windows, you want to re-create this 
default configuration, press the keypad-key sequence BLUE-MINUS (PF4 
followed by the MINUS (—) key). 


The basic features of the predefined displays are described in the 

next sections. As explained in other parts of this chapter, you can 
change certain characteristics of these displays, such as buffer size or 
display attributes. You can also create additional displays similar to the 
predefined displays. 


7.2.1 Predefined Source Display (SRC) 
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Note: See Chapter 6 for information about how to make source code 


available for display during a debugging session. 


The predefined display SRC (see Figure 7-1) is an automatically updated 
source display. 


You can use SRC to display source code in two basic ways: 


e By default, SRC automatically displays the source code for the module 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 


¢ Jn addition, because SRC has the source attribute by default, you 
can use it to display the source code for any part of your program as 
explained in Section 7.2.1.1. 


The name of the module whose source code is displayed is shown at the 
right of the display name, SRC. The numbers displayed at the left of the 
source code are the compiler-generated line numbers, as they might appear 
in a compiler-generated listing file. 
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As you execute the program under debugger control, SRC is updated 
automatically whenever execution is suspended. The arrow in the 
leftmost column indicates the source line to be executed next. Specifically, 
execution is suspended at the first VAX instruction associated with that 
source line. Thus, the line indicated by the arrow corresponds to the 
current PC value. The PC (program counter) is a VAX register that 
contains the memory address of the next instruction to be executed. 


If the debugger cannot locate source code for the routine in which 
execution is suspended (because, for example, the routine is a run-time 
library routine), it tries to display source code in the next routine down on 
the call stack for which source code is available. When displaying source 
code for such a routine, the debugger issues the following message: 


SDEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 
Displaying source in a caller of the current routine. 


Figure 7-2 illustrates this feature. The source display shows that a call 
to routine TYPE is currently active. TYPE corresponds to a FORTRAN 
run-time library procedure. No source code is available for that routine, so 
the debugger displays the source code of the calling routine. The output 
of a SHOW CALLS command, shown in the output display, identifies the 
routine where execution is suspended and the call sequence leading to that 
routine. 


In such cases, the arrow in the source window identifies the line to which 
execution returns after the routine call. Depending on the source language 
and coding style, this might be the line that contains the call statement or 
the next line. 
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Figure 7-2 Screen Mode Source Display When Source Code Is Not Available 


— SRC: module TEST-scroll-source 
S$DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC 
Displaying source in a caller of the current routine 
; CHARACTER* (*) ARRAYX 
-> : TYPE *, ARRAYX 


RETURN 


END 


— OUT-output 
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stepped to SHARESFORRTL+810 
module name routine name 
SHARESFORRTL SHARESFORRTL 
TEST 


*TEST 
*A 


sae PROMPT-error-program-prompt 


DBG> STEP 
DBG> SHOW CALLS 
DBG> 
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If your program was optimized during compilation, the source code 
displayed in SRC might not always represent the code that is actually 
executing. The predefined instruction display INST is useful in such 
cases, because it shows the exact VAX instructions that are executing. See 
Section 7.2.4. 


The built-in command that automatically updates display SRC is 
EXAMINE/SOURCE .%SOURCE_SCOPE\ %PC. The properties of this 
command are described in Section C.3.1 and Section 6.4. 


7.2.1.1. Displaying Source Code in Arbitrary Program Locations 
You can use display SRC to display source code throughout your program, 
if source code is available for display: 


You can scroll through the entire source display by pressing keypad 
keys 2 (scroll down) or 8 (scroll up) as explained in Section 7.3.1. 
This enables you to view any source line within the module in which 
execution is suspended. 


You can display the source code for any routine that is currently on 
the call stack by using the command SET SCOPE/CURRENT (see 
Section 7.2.1.2). 


Because SRC has the source attribute, you can display source code 
throughout your program by using the TYPE and EXAMINE/SOURCE 
commands: 


— To display arbitrary source lines use the TYPE command (see 
Section 6.3). 
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— To display the source line associated with a code location (for 
example, a routine declaration), use the EXAMINE/SOURCE 
command (see Section 6.4). 


When using the TYPE or EXAMINE/SOURCE command, make sure 
that the module in which you want to view source code is set first. 
Use the SHOW MODULE command to determine whether a particular 
module is set. Then use the SET MODULE command, if necessary 
(see Section 5.2). 


After manipulating the contents of display SRC, you can redisplay the 
location at which execution is currently suspended (the default behavior of 
SRC) by pressing keypad key 5. 


7.2.1.2 Displaying Source Code for a Routine on the Call Stack 
The command SET SCOPE/CURRENT enables you to display the source 
code for any routine that is currently on the call stack. For example, the 
following command updates display SRC so that it shows the source code 
for the caller of the routine in which execution is currently suspended: 


DBG> SET SCOPE/CURRENT 1 


To reset the default scope for displaying source code, enter the command 
CANCEL SCOPE. The command causes display SRC to show the source 
code for the routine at the top of the call stack, where execution is 
suspended. 


7.2.2 Predefined Output Display (OUT) 


Figure 7—1 and Figure 7—2 illustrate some typical debugger output in the 
predefined display OUT. 


Display OUT is a general purpose output display. By default, OUT has 
the output attribute and therefore displays any debugger output that is 
not directed to the source display SRC or the instruction display INST. For 
example, if display INST is not displayed or does not have the instruction 
attribute, any output that would otherwise update display INST is shown 
in display OUT. 

By default, OUT does not display debugger diagnostic messages (these 
appear in the PROMPT display). You can assign attributes to OUT so that 


it captures debugger input and diagnostics as well as normal output (see 
Section 7.7). 


7.2.3 Predefined Prompt Display (PROMPT) 


The predefined display PROMPT is the display in which the debugger 
prompts for input. Figure 7-1 and Figure 7-2 show PROMPT in its 
default location, the bottom sixth of the screen. 


By default, PROMPT has the program and error attributes, in addition to 
the prompt attribute. Therefore, by default, the debugger forces program 
output to PROMPT and prints diagnostic messages to that display. 
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PROMPT has different properties and restrictions than other displays. 
This is to eliminate possible confusion when manipulating that display: 


¢ The debugger always keeps PROMPT on top of the display pasteboard 
so it cannot be hidden by another display. You cannot hide PROMPT 
(with the DISPLAY/HIDE command), or remove PROMPT from the 
pasteboard (with the DISPLAY/REMOVE command), or permanently 
delete PROMPT (with the CANCEL DISPLAY command). 


¢ PROMPT can have the scroll attribute, so that it can be made the 
default target display for the MOVE and EXPAND commands. But 
you cannot scroll PROMPT. 


e You can move PROMPT anywhere on the screen, expand it to fill the 
full screen height, and contract it down to two lines. But PROMPT 
must always occupy the full width of the screen. Therefore, you cannot 
move, expand, or contract PROMPT horizontally. 


The debugger alerts you if you try to move or expand a display such that 
it is hidden by PROMPT. 


7.2.4 Predefined Instruction Display (INST) 
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Note: By default, the predefined instruction display INST is not shown 


on the screen and does not have the instruction attribute (see 
Section 7.2.4.1 and Section 7.2.4.2). 


Display INST is an automatically updated instruction display. It shows the 
decoded VAX assembly-language instruction stream of your program. This 
is the exact code that is executing, including the effects of any compiler 
optimization. An example is shown in Figure 7-3. 


This type of display is useful when debugging code that has been 
optimized. In such cases some of the code being executed might not 
match the source code that is shown in a source display. See Section 9.1 
for information about the effects of optimization. 


You can use INST in two basic ways: 


e By default, INST automatically displays the decoded instructions for 
the routine in which execution is currently suspended. This enables 
you to quickly determine your current debugging context. 


¢ In addition, if INST has the instruction attribute, you can use it 
to display the decoded instructions for any part of your program as 
explained in Section 7.2.4.2. 


The name of the routine whose instructions are displayed is shown at the 
right of the display name, INST. The numbers displayed at the left of the 
instructions are the compiler-generated source line numbers. 
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Figure 7~3 Screen Mode Instruction Display 




















== INST: routine SQUARESSMAIN 
TSTL B*16 (R11) 
: BLEQ SQUARESSMAIN\SLINE 16 
Line 10: MOVL B*4 (R11) ,R0 
: TSTL w*- -164 (R11) [RO] 
: BEOL So 13 
-~>ne 11: MOVL B*12(R11),R 
: MOVL B*4 (RAT) RO 
: MULL3 W*-164 (R11) [RO],W*-164 (R11) [RO] ,B*-84 Ga) [R1] 
Line 13: AOBLEQ B*16(R11),B“4 (R11) , SOUARESSMAIN\$LINE 
Line 16: PUSHAL L%*525 
MNEGL S*#1,-(SP) 
A 00Toieput 


stepped to SQUARESSMAIN\%SLINE 9 
9: DO 10 I= 1, N 


SQUARES SMAIN\N: 3 

SQUARES SMAIN\K: 0 

stepped to SQUARESSMAIN\%LINE 11 
SQUARES SMAIN\I: 1 
SQUARESSMAIN\K: 0 

~~ PROMPT-error-program-prompt 
DBG> STEP 

DBG> EXAMINE I,K 


DBG> 
ZK-6505-—GE 


As you execute the program under debugger control, INST is updated 
automatically whenever execution is suspended. The arrow in the leftmost 
column points to the instruction at which execution is suspended. This is 
the instruction that will be executed next and whose address is the current 
PC value. 


The built-in command that automatically updates display INST is 
EXAMINE/INSTRUCTION .%ZINST_SCOPE\ %PC. The properties of 
this command are described in Section C.3.4 and Section 4.3.1. 


7.2.4.1 Displaying the Instruction Display 
By default, display INST is marked as removed (see Section 7.3.2) from 
the display pasteboard and is not visible. To show display INST, use one 
of the following methods: 


e Press keypad key 7 to place displays SRC and INST side by side. 
This enables you to readily compare the source code and the decoded 
instruction stream. 


e Press the keypad key sequence PF1-7 to place displays INST and REG 
side by side. 


e Enter the command DISPLAY INST to place INST in its default or 
most recently defined location (see Section 7.3.2). 


1-9 


Using Screen Mode 
7.2 Debugger Predefined Displays 


7.2.4.2 Displaying Instructions in Arbitrary Program Locations 


You can use display INST to display decoded instructions throughout your 
program: 


e You can scroll through the entire instruction display by pressing 
keypad keys 2 (scroll down) or 8 (scroll up) as explained in 
Section 7.3.1. This enables you to view any instruction within the 
routine in which execution is suspended. 


¢ You can display the instruction stream for any routine that is currently 
on the call stack by using the command SET SCOPE/CURRENT (see 
Section 7.2.4.3). 


e If INST has the instruction attribute, you can display the instructions 
for any code location throughout your program by using the EXAMINE 
JAINSTRUCTION command: 


1 To assign INST the instruction attribute, use the command 
SELECT/INSTRUCTION INST (see Section 7.6.2 and Section 7.7). 
Note that the instruction attribute is automatically assigned to 
INST when you display it by pressing either keypad key 7 or the 
key sequence PF'1-7. 


2 To display the instructions associated with a code location 
(for example, a routine declaration), use the EXAMINE 
AINSTRUCTION command (see Section 4.3.1). 


If no display has the instruction attribute, the output of an EXAMINE 
/INSTRUCTION command is directed at display OUT. 


After manipulating the contents of display INST, you can redisplay the 
location at which execution is currently suspended (the default behavior of 
INST) by pressing keypad key 5. 


7.2.4.3 Displaying Instructions for a Routine on the Call Stack 


The command SET SCOPE/CURRENT enables you to display the 
instructions for any routine that is currently on the call stack. For 
example, the following command updates display INST so that it shows 
the instructions for the caller of the routine in which execution is currently 
suspended: 


DBG> SET SCOPE/CURRENT i 


To reset the default scope for displaying instructions, enter the command 
CANCEL SCOPE. The command causes display INST to show the 
instructions for the routine at the top of the call stack, where execution is 
suspended. 


7.2.09 Predefined Register Display (REG) 
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The predefined register display REG shows the current values, in 
hexadecimal format, of the VAX general registers (RO to R11, AP, FP, 
SP, PC), the four condition code bits (C, V, Z, and N) of the processor 
status longword (PSL), and as many of the top stack values as can be 
displayed through the window (see Figure 7-4). 
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Figure 7-4 Screen Mode Register Display 




















— SRC: module SQUARESSMAIN—scroll-sourc 


Sec -- Read the input array RO :00000000 R11:000004A0 +10:0002019B 
4: OPEN (UNIT=8, FILE=’ DATAF Rl :00000008 AP :7FF359CC +14:7FFE2BDC 
5: READ (8,*) N, (INARR(I), R2 :00000000 FP :7FF35980 +18:000009FF 
62°C R3 :7FF35994 SP :7FF35980 +1C:00000005 
fae © -- Square all non-zero e R4 :00000000 PC :0000064D +20:00000600 
-> 8: K = 0 R5 :00000000 PSL: C:0 2:0 +24:00000000 
9; D010 IT=1, N R6 :7FF35649 PSL: V:0 N:0 +28:00000001 
10: IF (INARR(I) .NE. 0) THEN R7 :8012F9E9 @SP:00000000 +2C:0000000D 
Tes K=K+1 R8 :7FFECA52 +04:08000000 +30:7FF359CC 
23 OUTARR(K) = INAR RO :7FFECCSA +08:7FF359CC +34:00000000 
Lae ENDIF R10: 7FFED7D4 +0C:7FF359B8 +38:00020073 





— OUT- output 
stepped to SQUARESSMAIN\SLINE 4 
stepped to SQUARESSMAIN\%LINE 5 
stepped to SQUARESSMAIN\%LINE 8 
SQUARESSMAIN\I: > 
SQUARESSMAIN\K: 0 
SQUARESSMAIN\N: 4. 









~~ PROMPT — error-program—-prompt 
DBG> STEP 

DBG> EXAMINE I,K,N 

DBG> 


ZK-6506-GE 





The register values displayed are for the routine in which execution is 
currently suspended. The values are updated whenever the debugger 
takes control. Any changed values are highlighted. 


REG is initially marked as removed (see Section 7.3.2) from the display 
pasteboard and is not visible. You must use the DISPLAY command (or 
the keypad key sequence GOLD-7) to show the REG display. Pressing 
GOLD-7 enables you to place REG next to display INST. 


If the register window is made larger, the debugger fills the remaining 
space with information contained in the user call stack. : 


REG does not display the current values of the VAX vector registers. To 
display data contained in vector registers or vector control registers in 
screen mode, use a DO display. (See Section 7.6.1.) 


7.3 Manipulating Existing Displays 
This section explains how to perform the following functions: 
e Use the SELECT and SCROLL commands to scroll a display. 


¢ Use the DISPLAY command to show, hide, or remove a display; the 
CANCEL DISPLAY command to permanently delete a display; and the 
SHOW DISPLAY command to identify the displays that currently exist 
and their order in the display list. 
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e Use the MOVE command to move a display across the screen. 


e Use the EXPAND command to expand or contract a display. 


Note also that Section 7.5 and Section 7.6 discuss more advanced 
techniques for modifying existing displays with the DISPLAY command— 
how to change the display window and the type of information displayed. 


7.3.1. Scrolling a Display 


A display usually has more lines of text (and possibly longer lines) than 
can be seen through its window. The SCROLL command enables you to 
view text that is hidden beyond a window’s border. You can scroll through 
all displays except for the PROMPT display. 


The easiest way to scroll displays is with keypad keys, as described later 
in this section. First, use of the relevant commands is explained. 


You can specify a display explicitly with the SCROLL command. Typically, 
however, you first use the SELECT/SCROLL command to select the 
current scrolling display. This display then has the scroll attribute and is © 
the default display for the SCROLL command. You then use the SCROLL 
command with no parameter to scroll that display up or down by a 
specified number of lines, or to the right or left by a specified number 

of columns. The direction and distance scrolled are specified with the 
command qualifiers (/UP:n, /RIGHT:n, and so on). 


In the following example, the SELECT command selects display OUT as 
the current scrolling display (/SCROLL can be omitted because it is the 
default qualifier); the SCROLL command then scrolls OUT to reveal text 
18 lines down: 


DBG> SELECT OUT 
DBG> SCROLL/DOWN:18 


Several useful SELECT and SCROLL command lines are assigned to 
keypad keys (see Appendix B for the keypad diagram): 


e Pressing key 3 assigns the scroll attribute to the next display in the 
display list after the current scrolling display. So, to select a display 
as the current scrolling display, press key 3 repeatedly until the word 
"scroll" appears on the top line of that display. 


e Press key 8, 2, 6, or 4 to scroll up, down, right, or left, respectively. 
The amount of scroll depends on which key state you use (DEFAULT, 
GOLD, or BLUE). 


7.3.2 Showing, Hiding, Removing, and Canceling a Display 


7-12 


The DISPLAY command is the most versatile command for creating and 
manipulating displays. In its simplest form, the command puts an existing 
display on top of the pasteboard, where it appears through its current 
window. For example, the following command shows the display INST 
through its current window: 


DBG> DISPLAY INST 
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Pressing keypad key 9, which is bound to the command DISPLAY 
%NEXTDISP, enables you to achieve this effect conveniently. The built- 
in function ZNEXTDISP signifies the next display in the display list 
(Appendix D identifies all screen-related built-in functions). Each time you 
press key 9, the next display in the list is put on top of the pasteboard, in 
its current window. 


Note that, by default, the top line of display OUT (which identifies the 
display) coincides with the bottom line of display SRC. If SRC is on top 
of the pasteboard, its bottom line hides the top line of OUT (keep this in 
mind when using the DISPLAY command and associated keypad keys to 
put various displays on top of the pasteboard). 


To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE 
command. This command changes the order of that display in the display 
list. 


To remove a display from the pasteboard so that it is no longer seen (yet is 
not permanently deleted), use the DISPLAY/REMOVE command. To put a 
removed display back on the pasteboard, use the DISPLAY command. 


To delete a display permanently, use the CANCEL DISPLAY command. 
To re-create the display, use the DISPLAY command as described in 
Section 7.4. 


Note that you cannot hide, remove, or delete the PROMPT display. 


To identify the displays that currently exist, use the SHOW DISPLAY 
command. They are listed according to their order on the display list. The 
display that is on top of the pasteboard is listed last. 


See the command dictionary for information about the various options 
provided by the DISPLAY command qualifiers. Note also that the 
DISPLAY command accepts optional parameters that enable you to modify 
other characteristics of existing displays, namely the display window 

and the type of information displayed. The techniques are discussed in 
Section 7.5 and Section 7.6. 


7.3.3 Moving a Display Across the Screen 


Use the MOVE command to move a display across the screen. The 
qualifiers /UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction 
and the number of lines or columns by which to move the display. If you 
do not specify a display, the current scrolling display is moved. 


The easiest way to move a display is by using keypad keys: 
¢ Press key 3 repeatedly as needed to select the current scrolling display. 


¢ Put the keypad in the MOVE state, then use keys 8, 2, 4, or 6 to move 
the display up, down, left, or right, respectively (see Appendix B). 
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7.3.4 Expanding or Contracting a Display 


Use the EXPAND command to expand or contract a display. The qualifiers 
/UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the 
number of lines or columns by which to expand or contract the display (to 
contract a display, specify negative integer values with these qualifiers). If 
you do not specify a display, the current scrolling display is expanded or 
contracted. 


The easiest way to expand or contract a display is by using keypad keys. 
¢ Press key 3 repeatedly as needed to select the current scrolling display. 


e Put the keypad in the EXPAND or CONTRACT state, then use keys 
8, 2, 4, or 6 to expand or contract the display vertically or horizontally 
(see Appendix B). 


Note that the PROMPT display cannot be contracted (or expanded) 
horizontally. Also, it cannot be contracted vertically to less than two 
lines. 





7.4 Creating a New Display 
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To create a new screen display, use the DISPLAY command. The basic 
syntax is as follows: 


DISPLAY display-name [AT window-specification] [display-kind] 


The display name can be any name that is not already used to name 

a display (use the SHOW DISPLAY command to identify all existing 
displays). When you create a new display, it is placed on top of the 
pasteboard, on top of any existing displays (except for the predefined 
PROMPT display, which cannot be hidden). The display name appears at 
the top left corner of the display window. 


Section 7.5 explains the options for specifying windows. If you do not 
provide a window specification, the display is positioned in the upper or 
lower half of the screen, alternating between these locations as you create 
new displays. 


Section 7.6 explains the options for specifying display kinds. If you do not 
specify a display kind, an output display is created. 


For example, the following command creates a new output display named 
OUT2. The window associated with OUT2 is either the top or bottom half 
of the screen. 


DBG> DISPLAY OUT2 
The following command creates a new "DO" display named EXAM_XY 
that is located in the right third quarter (RQ3) of the screen. This display 


shows the current value of variables X and Y and is updated whenever the 
debugger gains control from the program. 


DBG> DISPLAY EXAM XY AT RQ3 DO (EXAMINE X,Y) 


See the command dictionary for information about the various options 
provided by the DISPLAY command qualifiers. 
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7.5 Specifying a Display Window 
Display windows can occupy any rectangular portion of the screen. 


You can specify a display window when you create a display with the 
DISPLAY command. You can also change the window currently associated 
with a display by specifying a new window with the DISPLAY command. 
When specifying a window, you have the following options: 


e Specify a window in terms of lines and columns. 
e Use the name of a predefined window, such as H1. 


e Use the name of a window definition previously established with the 
SET WINDOW command. 


Each of these techniques is described in the next sections. When specifying 
windows, keep in mind that the PROMPT display always remains on top 
of the display pasteboard and, therefore, occludes any part of another 
display that shares the same region of the screen. 


Display windows, regardless of how specified, are dynamic. This means 
that, if you use a SET TERMINAL command to change the screen height 
or width, the window associated with a display expands or contracts in 
proportion to the new screen height or width. 


7.5.1. Specifying a Window in Terms of Lines and Columns 


The general form of a window specification is (start-line,line-count[,start- 
column,column-count]). For example, the following command creates 
the output display CALLS and specifies that its window be 7 lines deep 
starting at line 10, and 30 columns wide starting at column 50: 


DBG> DISPLAY CALLS AT (10,7,50,30) 


If you do not specify start-column or column-count, the window occupies 
the full width of the screen. 


7.5.2 Predefined Windows 


The debugger provides many predefined windows. These have short 
symbolic names that you can use in the DISPLAY command instead of 
having to specify lines and columns. For example, the following command 
creates the output display ZIP and specifies that its window be RH1 (the 
top right half of the screen). 


DBG> DISPLAY ZIP AT RH1 


The SHOW WINDOW command identifies all predefined window 
definitions, as well as those you create with the SET WINDOW command. 
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7.5.3 Creating a New Window Definition 


Although the predefined windows should be adequate for most situations, 
you can also create a new window definition with the SET WINDOW 
command. This command, which has the following form, associates a 
window name with a window specification: 


SET WINDOW window-name AT (start-line,line-count[,start-col,col-count}) 


After creating a window definition, you can simply use its name (like 
that of a predefined window) in a DISPLAY command. In the following 
example, the window definition MIDDLE is established. That definition is 
then used to display OUT through the window MIDDLE. 


DBG> SET WINDOW MIDDLE AT (9,4,30,20) 
DBG> DISPLAY OUT AT MIDDLE 


To identify all current window definitions, use the SHOW WINDOW 
command. To delete a window definition, use the CANCEL WINDOW 
command. | 


7.6 Specifying the Display Kind 
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Every display has a display kind. The display kind determines the type of 
information a display contains and how that information is generated. 


Typically, you specify a display kind when you use the DISPLAY command 
to create a new display (if you do not specify a display kind, an output 
display is created). You can also use the DISPLAY command to change 
the display kind of an existing display. The keywords and associated 
parameters with which you specify a display kind are listed below. Each 
of these options is explained in the sections that follow (refer also to the 
displays illustrated in Section 7.2). 


DO (command-list) 
INSTRUCTION 
INSTRUCTION (command) 
OUTPUT 

REGISTER 

SOURCE 

SOURCE (command) 


The contents of a register display are generated and updated automatically 
by the debugger. The contents of other kinds of displays are generated by 
commands, and these display kinds fall into two general groups. 


A display that belongs to one of the following display kinds has its contents 
updated automatically according to the command or command list you 
supply when defining that display: 


DO (command-list) 
INSTRUCTION (command) 
SOURCE (command) 
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The command list specified is executed each time the debugger gains 
control from your program, provided the display is not marked as removed. 
The output of the commands forms the new contents of the display. If the 
display is marked as removed, the debugger does not execute the command 
list until you view that display (marking that display as unremoved). 


A display that belongs to one of the following display kinds derives its 
contents from commands that you enter interactively: “ 


INSTRUCTION 
OUTPUT 
SOURCE 


To direct debugger output to a specific display in this group, you must 
first select it with the SELECT command. The technique is explained in 
the next sections and, in further detail, in Section 7.7. After a display 
is selected for a certain type of output, the output from your commands 
forms the contents of the display. 


The default size of the memory buffer associated with any newly created 
display is 64 lines. For source and instruction displays, the size of the 
buffer only affects performance. In the case of a source display, source files 
are paged in as necessary as you scroll through the module. In the case 
of an instruction display, the instructions are decoded from the image as 
necessary as you scroll through the routine. 


For output and DO displays, the buffer size defines how many lines of text 
the display holds. If you add more text to the display, the oldest lines are 
discarded to make room for the new text. You can use the /SIZE qualifier 
on the DISPLAY command to change the buffer size. 


7.6.1 DO(command{; ... ]) Display Kind 


A DO display is an automatically updated display. The commands in the 
command list are executed in the order listed each time the debugger 
gains control from your program. Their output forms the content of the 
display, erasing any previous content. 


For example, the following command creates the DO display CALLS at 
window Q3. Each time the debugger gains control from the program, 
the SHOW CALLS command is executed and the output is displayed in 
CALLS, replacing any previous contents. 


DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 


The following command creates a DO display named V2_DISP that shows 
the contents of elements 4 to 7 of the VAX vector register V2 (using 
FORTRAN array syntax). The display is automatically updated whenever 
the debugger gains control from the program: 


DBG> DISPLAY V2 DISP AT RQ2 DO (EXAMINE %V2 (4:7) ) 
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7.6.2 INSTRUCTION Display Kind 


An instruction display shows the output of an EXAMINEANSTRUCTION 
command within the assembly-language instruction stream of a routine. 
Because the instructions displayed are decoded from the image being 
debugged and show the exact code that is executing, this kind of display is 
particularly useful in helping you debug optimized code (see Section 9.1). 


In the display, one line is devoted to each instruction. Source line numbers 
corresponding to the instructions are displayed in the left column. The 
instruction at the location being examined is centered in the display and is 
marked by an arrow in the left column. 


Before anything can be written to an instruction display, you must select 
it as the current instruction display with the SELECT/INSTRUCTION 
command. 


In the following example, the DISPLAY command creates the instruction 
display INST2 at RH1. The SELECT/INSTRUCTION command then 
selects INST2 as the current instruction display. When the EXAMINE 
INSTRUCTION X command is executed, window RH1 fills with the 
instruction stream surrounding the location denoted by X. The arrow 
points to the instruction at location X, which is centered in the display. 


DBG> DISPLAY INST2 AT RH1 INSTRUCTION 
DBG> SELECT/INSTRUCTION INST2 
DBG> EXAMINE/INSTRUCTION X 


Each subsequent EXAMINE/INSTRUCTION command updates the 
display. 


7.6.3. INSTRUCTION (command) Display Kind 
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This is an instruction display that is automatically updated with the 
output of the command specified. That command, which must be an 
EXAMINE/INSTRUCTION command, is executed each time the debugger 
gains control from your program. 


For example, the following command creates the instruction display INST3 
at window RS45. Each time the debugger gains control, the built-in 
command EXAMINEANSTRUCTION .%ZINST_SCOPE\ %PC is executed, 
updating the display. 


DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST .%INST_SCOPE\%PC) 


This command creates a display that functions like the predefined display 
INST. The built-in EXAMINE/INSTRUCTION command displays the 
instruction at the current PC value in the current scope (see Section C.3.4). 


If an automatically updated instruction display is selected as the current 
instruction display, it is updated like a simple instruction display by an 
interactive EXAMINE/INSTRUCTION command (in addition to being 
updated by its built-in command). 
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7.6.4 OUTPUT Display Kind 


An output display shows any debugger output that is not directed to 
another display. New output is appended to the previous contents of the 
display. 


Before anything can be written to an output display, it must be selected 
as the current output display with the SELECT/OUTPUT command, or as 
the current error display with the SELECT/ERROR command, or as the 
current input display with the SELECT/INPUT command. See Section 7.7 
for more information about using the SELECT command with output 
displays. 


In the following example, the DISPLAY command creates the output 
display OUT2 at window T2 (the display kind OUTPUT could have been 
omitted from this example, because it is the default kind). The SELECT 
/OUTPUT command then selects OUT2 as the current output display. 
These two commands create a display that functions like the predefined 
display OUT. 

DBG> DISPLAY OUT2 AT T2 OUTPUT 

DBG> SELECT/OUTPUT OUT2 


OUT2 now collects any debugger output that is not directed to another 
display. For example: 


¢ The output of a SHOW CALLS command goes to OUT2. 


e If no instruction display has been selected as the current instruction 
display, the output of an EXAMINEANSTRUCTION command goes to 
OUTZ2. 


e By default, debugger diagnostic messages are directed to the PROMPT 
display. They can be directed to OUT2 with the SELECT/ERROR 
command. 


7.6.5 REGISTER Display Kind 


A register display is an automatically updated display that shows the 
current values, in hexadecimal format, of the VAX general registers (RO to 
R11, AP, FP, SP, and PC), the four condition code bits (C,V, Z, and N) of the 
processor status longword (PSL), and as many of the top call stack values 
as can be displayed in the window (see Figure 7-4). 


The register values displayed are for the routine in which execution is 
currently suspended. The values are updated whenever the debugger 
takes control. Any changed values are highlighted. 


A register display does not display the current values of the VAX vector 
registers. To display data contained in vector registers or vector control 
registers in screen mode, use a DO display. (See Section 7.6.1.) 
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7.6.6 SOURCE Display Kind 


A source display shows the output of a TYPE or EXAMINE/SOURCE 
command within the source code of a module, if that source code is 
available. Source line numbers are displayed in the left column. The 
source line that is the output of the command is centered in the display 
and is marked by an arrow in the left column. If a range of lines is 
specified with the TYPE command, the lines are centered in the display, 
but no arrow is shown. 


Before anything can be written to a source display, you must select it as 
the current source display with the SELECT/SOURCE command. 


In the following example, the DISPLAY command creates the source 
display SRC2 at Q2. The SELECT/SOURCE command then selects SRC2 
as the current source display. When the command TYPE 34 is executed, 
window RH1 fills with the source code surrounding line 34 of the module 
being debugged. The arrow points to line 34, which is centered in the 
display. 


DBG> DISPLAY SRC2 AT Q2 SOURCE 
DBG> SELECT/SOURCE SRC2 
DBG> TYPE 34 


Each subsequent TYPE or EXAMINE/SOURCE command updates the 
display. 


7.6.7 SOURCE (command) Display Kind 
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This is a source display that is automatically updated with the output 
of the command specified. That command, which must be an EXAMINE 
/SOURCE or TYPE command, is executed each time the debugger gains 
control from your program. 


For example, the following command creates a source display SRC3 
at window RS45. Each time the debugger gains control, the built-in 
command EXAMINE/SOURCE .%SOURCE_SCOPE\ %PC is executed, 
updating the display. 


DBG> DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE .%SOURCE SCOPE\%PC) 


This command creates a display that functions like the predefined display 
SRC. The built-in EXAMINE/SOURCE command displays the source line 
for the current PC value in the current scope (see Section C.3.1). 


If an automatically updated source display is selected as the current 
source display, it is updated like a simple source display by an interactive 
EXAMINE/SOURCE or TYPE command (in addition to being updated by 
its built-in command). 
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7.6.8 PROGRAM Display Kind 


The PROMPT display belongs to the special display kind "program." Note 
that PROMPT is the only display of that kind. You cannot specify that 
display kind in a DISPLAY command. 


To avoid possible confusion, the PROMPT display has several restrictions 
(see Section 7.2.3). 


7.7 Assigning Display Attributes 


In screen mode, the output from commands you enter interactively is 
directed to various displays according to the type of output and the 
attributes assigned to these displays. For example, debugger diagnostic 
messages go to the display that has the error attribute (the current error 
display). By assigning one or more attributes to a display, you can mix or 
isolate different kinds of information. 


The attributes have the following names: error, input, instruction, output, 
program, prompt, scroll, and source. When a display is assigned an 
attribute, the name of that attribute appears in lowercase letters on the 
top border of its window, to the right of the display name. Note that the 
scroll attribute does not affect debugger output but is used to control the 
default display for the SCROLL, MOVE, and EXPAND commands. 


By default, attributes are assigned to the predefined displays as follows: 
e SRC has the source and scroll attributes. 

¢ OUT has the output attribute. 

e PROMPT has the prompt, program, and error attributes. 


To assign an attribute to a display, use the SELECT command with the 
qualifier of the same name as the attribute. In the following example, 
the DISPLAY command creates the output display ZIP. The SELECT 
/OUTPUT command then selects ZIP as the current output display—the 
display that has the output attribute. After this command is executed, the 
word "output" disappears from the top border of the predefined output 
display OUT and appears instead on display ZIP, and all debugger output 
formerly directed to OUT is now directed to ZIP. 


DBG> DISPLAY ZIP OUTPUT 
DBG> SELECT/OUTPUT ZIP 


Specific attributes can be assigned only to certain display kinds. The 
following list identifies each of the SELECT command qualifiers, its effect, 
and the display kinds to which you can assign that attribute. 
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SELECT 

Qualifier Description 

/ERROR Selects the specified display as the current error display. Directs 
any subsequent debugger diagnostic message to that display. It 
must be either an output display or the PROMPT display. If no 
display is specified, selects the PROMPT display as the current 
error display. 

[INPUT Selects the specified display as the current input display. 


Echoes any subsequent debugger input in that display. It 
must be an output display. If no display is specified, unselects 
the current input display: debugger input is not echoed to any 
display. 


[INSTRUCTION Selects the specified display as the current instruction display. 
Directs the output of any subsequent EXAMINE/INSTRUCTION 
command to that display. It must be an instruction display. 
Keypad key sequence BLUE-COMMA selects the next 
instruction display in the display list as the current instruction 
display. If no display is specified, unselects the current 
instruction display: no display has the instruction attribute. 


/OUTPUT Selects the specified display as the current output display. 
Directs any subsequent debugger output to that display, except 
where a particular type of output is being directed to another 
display (such as diagnostic messages going to the current error 
display). The specified display must be either an output display 
or the PROMPT display. Keypad key sequence GOLD-3 selects 
the next output display in the display list as the current output 
display. If no display is specified, selects the PROMPT display 
as the current output display. 


/PROGRAM Selects the specified display as the current program display. 
Tries to force any subsequent program input or output to that 
display. Currently, only the PROMPT display can be specified. 
lf no display is specified, unselects the current program display: 
program output is no longer forced to the PROMPT display. 


/PROMPT Selects the specified display as the current prompt display, 
where the debugger prompts for input. Currently, only the 
PROMPT display can be specified. You cannot unselect the 
PROMPT display. 


/SCROLL Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. Key 3 selects 
as the current scrolling display the next display in the display 
list after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the scroll 
attribute. 


1-22 


Using Screen Mode 
7.7 Assigning Display Attributes 


SELECT 
Qualifier Description 
/SOURCE Selects the specified display as the current source display. 


Directs the output of any subsequent TYPE or EXAMINE 
/SOURCE command to that display. It must be a source display. 
Keypad key sequence BLUE-3 selects the next source display 
in the display list as the current source display. If no display is 
specified, unselects the current source display: no display has 
the source attribute. 


Subject to the restrictions listed, a display can have several attributes. In 
the preceding example, ZIP was selected as the current output display. 

In the next example, ZIP is further selected as the current input, error, 
and scrolling display. After these commands are executed, debugger input, 
output, and diagnostics are logged in ZIP in the proper sequence as they 
occur, and ZIP is the current scrolling display. 


DBG> SELECT/INPUT/ERROR/SCROLL ZIP 


To identify the displays currently selected for each of the display 
attributes, use the SHOW SELECT command. 


If you use the SELECT command with a particular qualifier but without 
specifying a display name, the effect is typically to de-assign that attribute 
(to "unselect" the display that had the attribute). The exact effect depends 
on the attribute, as described in the preceding list. 


7.8 A Sample Display Configuration 


How to best use screen mode depends on your personal style and on what 
type of bug you are looking for. You might be satisfied to simply use the 
predefined displays. On the other hand, especially if you have access to 
a larger screen, you might want to create additional displays for various 
purposes. The following example might give you some ideas. 


Assume you are debugging in a high-level language and are interested in 
tracing the execution of your program through several routine calls. 


First set up the default screen configuration—that is, SRC in H1, OUT in 
S45, and PROMPT in S6 (the keypad key sequence BLUE-MINUS gives 
this configuration). SRC shows the source code of the module in which 
execution is suspended. 


The next command creates a source display named SRC2 in RH1 that 
shows the PC value at scope 1 (one level down the call stack, at the call to 
the routine in which execution is suspended): 


DBG> DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE .1\%PC) 


Thus the left half of your screen shows the currently executing routine, 
whereas the right half shows the caller of that routine. 


The next command creates a DO display named CALLS at S4 that 
executes the SHOW CALLS command each time the debugger gains 
control from the program: 


DBG> DISPLAY CALLS AT S4 DO (SHOW CALLS) 
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Because the top half of OUT is now hidden by CALLS, make OUT’s 
window smaller: 


DBG> DISPLAY OUT AT S5 


You can create a similar display configuration with instruction displays 
instead of source displays. 


7.9 saving Displays and the Screen State 


The SAVE command enables you to make a "snapshot" of an existing 
display and save that copy as a new display. This is useful if, for example, 
you later want to refer to the current contents of an automatically updated 
display (such as a DO display). 


In the following example, the SAVE command saves the current contents 
of display CALLS into display CALLS4, which is created by the command: 


DBG> SAVE CALLS AS CALLS4 


The new display is removed from the pasteboard. So, to view its contents 
use the DISPLAY command: 


DBG> DISPLAY CALLS4 


The EXTRACT command has two uses. First, it enables you to save the 
contents of a display in a text file. For example, the following command 
extracts the contents of display CALLS, appending the resulting text to 
the file COB34.TXT: 


DBG> EXTRACT/APPEND CALLS COB34 


Second, the EXTRACT/SCREEN_LAYOUT command enables you to create 
a command procedure that can later be invoked during a debugging 
session to re-create the previous state of the screen. In the following 
example, the EXTRACT/SCREEN_LAYOUT command creates a command 
procedure with the default specification SYS$DISK:[ ]DBGSCREEN.COM. 
The file contains all the commands needed to re-create the current state of 
the screen. 


DBG> EXTRACT/SCREEN LAYOUT 


DBG> @DBGSCREEN 


Note that you cannot save the PROMPT display as another display, or 
extract it into a file. 


7.10 | Changing the Screen Height and Width 
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During a debugging session, you might want to change the height or width 
of your terminal screen. One reason might be to accommodate long lines 
that would wrap if displayed across 80 columns. Or, if you are using a 
workstation, you might want to reformat your debugger window relative to 
other windows. 


Using Screen Mode 
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To change the screen height or width, use the SET TERMINAL command. 
The general effect of the command is the same whether you are at a 
VT-series terminal or at a workstation. 


In this example, assume you are using a workstation in its default 
emulated VT100-screen mode, with a screen size of 24 lines by 80 columns. 
You have invoked the debugger and are using it in screen mode. You now 
want to take advantage of the larger screen. The following command 
increases the screen height and width of the debugger window to 35 lines 
and 110 columns respectively: 


DBG> SET TERMINAL/PAGE:35/WIDTH:110 


By default, all displays are dynamic. A dynamic display automatically 
adjusts its window dimensions in proportion when a SET TERMINAL 
command changes the screen height or width. This means that, when 
using the SET TERMINAL command, you preserve the relative positions 
of your displays. The ([NOJDYNAMIC qualifier on the DISPLAY command 
enables you to control whether or not a display is dynamic. If a display 

is not dynamic, it does not change its window coordinates after you enter 
a SET TERMINAL command (you can then use the DISPLAY, MOVE, 

or EXPAND commands, or various keypad key combinations, to move or 
resize a display). 


To see the current terminal width and height being used by the debugger, 
use the SHOW TERMINAL command. 


Note that the debugger’s SET TERMINAL command does not affect the 
terminal screen size at DCL level. When you exit the debugger, the 
original screen size is maintained. 
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8 Additional Convenience Features 


This chapter describes the following debugger convenience features not 
described elsewhere in this manual: 


e Using debugger command procedures 
e Using an initialization file for a debugging session 
e Logging a debugging session into a file 


e Defining symbols to represent commands, address expressions, or 
values 


e Assigning debugger commands to function keys 
e Using control structures to enter commands 


e Calling arbitrary routines linked with your program 





8.1 Using Debugger Command Procedures 


A debugger command procedure is a sequence of commands contained in 
a file. You can direct the debugger to execute a command procedure to 
recreate a debugging session, to continue a previous session, or to avoid 
typing the same debugger commands many times during a debugging 
session. You can pass parameters to command procedures. 


As with DCL command procedures, you execute a debugger command 
procedure by preceding its file specification with an at sign (@). The @ is 
the execute procedure command. 


Debugger command procedures are especially useful when you regularly 
perform a number of standard set-up debugger commands, as specified in 
a debugger initialization file (see Section 8.2). You can also use a debugger 
log file as a command procedure (see Section 8.3). 


8.1.1 Basic Conventions 


The following is a sample debugger command procedure named 
BREAK7.COM: 


{ *x*x*xxkk Debugger Command Procedure BREAK7.COM ***** 

SET BREAK/AFTER:3 S$LINE 120 DO (EXAMINE K,N,J,X(K); GO) 
SET BREAK/AFTER:3 SLINE 160 DO (EXAMINE K,N,J,X(K),S; GO) 
SET BREAK %SLINE 90 


When you execute this command procedure with the execute procedure 
(@) command, the commands listed in the procedure are executed in the 
order they appear. 


The rules entering commands in command procedures are listed in 
Section 1 of the command dictionary. 
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You can pass parameters to a command procedure. See Section 8.1.2 for 
conventions on passing parameters. 


You can enter the @ command like any other debugger command—that is, 
directly from the terminal, from within another command procedure, from 
within a DO clause in a command such as SET BREAK, or from within a 
DO clause in a screen display definition. 


If you do not supply a full file specification with the @ command, 

the debugger assumes SYS$DISK:[ ]DEBUG.COM as the default file 
specification for command procedures. For example, you would enter the 
following command line to execute command procedure BREAK7.COM, 
located in your current default directory: 


DBG> @BREAK7 


The SET ATSIGN command enables you to change any or all fields of the 
default file specification, SYS$DISK:[ ]DEBUG.COM. The command SHOW 
ATSIGN identifies the default file specification for command procedures. 


By default, commands read from a command procedure are not echoed. If 
you enter the command SET OUTPUT VERIFY, all commands read from a 
command procedure are echoed on the current output device, as specified 
by DBG$OUTPUT (the default output device is SYS$OUTPUT). Use the 
SHOW OUTPUT command to determine whether commands read from a 
command procedure are echoed or not. 


If the execution of a command in a command procedure results in a 
diagnostic of severity "warning" or greater, the command is aborted, but 
execution of the command procedure continues at the next command line. 


8.1.2 Passing Parameters to Command Procedures 
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As with DCL command procedures, you can pass parameters to debugger 
command procedures. However, the technique is different in several 
respects. 


Subject to the conventions described here, you can pass as many 
parameters as you want to a debugger command procedure. The 
parameters can be address expressions, commands, or value expressions in 
the current language. You must surround command strings in quotation 
marks ("), and you must separate parameters by commas (, ). 


A debugger command procedure to which you pass parameters must 
contain a DECLARE command line that binds each actual (passed) 
parameter to a formal parameter (a symbol) declared within the command 
procedure. 


The DECLARE command is valid only within a command procedure. Its 
format is as follows: 


DECLARE p-name:p-kind [,p-name:p-kind [,...]] 


Each p-name:p-kind pair associates a formal parameter (p-name) with a 
parameter kind (p-kind). The valid p-kind keywords are as follows: 
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ADDRESS Causes the actual parameter to be interpreted as an address 
expression. 


COMMAND Causes the actual parameter to be interpreted as a command. 


VALUE Causes the actual parameter to be interpreted as a value expression 
In the current language. 


The following example illustrates what happens when a parameter is 
passed to a command procedure. The command DECLARE K:ADDRESS, 
within command procedure EXAM.COM, declares the formal parameter K. 
The actual parameter passed to EXAM.COM is interpreted as an address 
expression. The command EXAMINE K displays the value of that address 
expression. The command SET OUTPUT VERIFY causes the commands 
to echo when they are read by the debugger. 


| *xkxxk Debugger Command Procedure EXAM.COM ***x** 
SET OUTPUT VERIFY 

DECLARE K:ADDRESS 

EXAMINE K 


The next command line executes EXAM.COM, passing the actual 
parameter ARR4. Within EXAM.COM, ARR4 is interpreted as an address 
expression (an array variable, in this case). 


DBG> @EXAM ARR4 
SDEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE K:ADDRESS 


EXAMINE K 

PROG 8\ARR4 
(1): 18 
(2)2 i 
(3): 0 
(4): 1 


SDEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 


Each p-name:p-kind pair specified by a DECLARE command binds one 
parameter. So, for instance, if you want to pass five parameters to a 

command procedure, you need five corresponding p-name:p-kind pairs. 
The pairs are always processed in the order in which you specify them. 


For example, the next command procedure, EXAM_GO.COM accepts two 
parameters, an address expression (L) and a command string (M). The 
address expression is then examined and the command is executed: 


1 **k*k*X Debugger Command Procedure EXAM GO.COM ***** 

DECLARE L:ADDRESS, M:COMMAND 

EXAMINE L; M 

The following example shows how you could execute EXAM_GO.COM, 
passing a variable X to be examined and a command @DUMP.COM to be 
executed: 


DBG> @EXAM GO X, "@DUMP" 


The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a 
command procedure. The value of 27 PARCNT is the number of actual 
parameters passed to the command procedure. 
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The %PARCNT built-in symbol is illustrated in the following example. The 
command procedure, VAR.DBG, contains the following lines: 


| *xx*k* Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

! Display the number of parameters passed: 

EVALUATE SPARCNT 

! Loop as needed to bind all passed parameters and obtain their values: 
FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 


The following command line executes VAR.DBG, passing the parameters 
12, 37, and 45: 


DBG> @VAR.DBG 12,37,45 

SDEBUG-I-VERIFYIC, entering command procedure VAR.DBG 

! Display the number of parameters passed: 

EVALUATE SPARCNT 

S 

! Loop as needed to bind all passed parameters and obtain their values: 
FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 


SDEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 
DBG> 


When VAR.DBG is executed, Z7PARCNT has the value 3. Therefore, the 
FOR loop within VAR.DBG is repeated 3 times. The FOR loop causes the 
DECLARE command to bind each of the three actual parameters (starting 
with 12) to a new declaration of X. Each actual parameter is interpreted as 
a value expression in the current language, and the command EVALUATE 
X displays that value. 


Using a Debugger Initialization File 


A debugger initialization file is a command procedure, assigned the logical 
name DBG$INIT, that the debugger automatically executes at debugger 
start up. Every time you invoke the debugger, the commands contained in 
the file are automatically executed. 


An initialization file contains any command lines you might always 
enter at the start of a debugging session to either tailor your debugging 
environment or control the execution of your program in a predetermined 
way from run to run. 


For example, you might have a file DEBUG_START4.COM containing the 
following commands: 
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f **ekk* Debugger Initialization File DEBUG START4.COM ***%**x 

! Log debugging session into default log file (SYSS$DISK: [] DEBUG. LOG) 

SET OUTPUT LOG 

! 

! Echo commands as they are read from command procedures: 

SET OUTPUT VERIFY 

! 

! If source files are not in current default directory, use [SMITH.SHARE] 
SET SOURCE [], [SMITH.SHARE] 

| 


! Invoke screen mode: 
SET MODE SCREEN 
I 


! Define the symbol SB as the command SET BREAK: 
DEFINE/COMMAND SB = "SET BREAK" 
I 


! Assign the command SHOW MODULE * to keypad key 7: 
DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 


To make this file a debugger initialization file, use the DCL command 
DEFINE. For example: 


S$ DEFINE DBGSINIT WORK: [JONES .DBGCOMFILES] DEBUG START4.COM 





Logging a Debugging Session into a File 


A debugger log file maintains a history of a debugging session. During 
the debugging session, each command entered and the resulting debugger 
output are stored in the file. 


The following is an example of a debugger log file. 


SHOW OUTPUT | 

!noverify, terminal, noscreen_log, logging to DSK2: [JONES.P7]DEBUG.LOG;1 
SET STEP NOSOURCE 

SET TRACE SLINE 30 

SET BREAK %LINE 60 


SHOW TRACE 
!'tracepoint at PROG4\%SLINE 30 
GO 


ltrace at PROG4\S%SLINE 30 
'break at PROG4\%SLINE 60 


The DBG> prompt is not recorded, and the debugger output is commented 
out with exclamation points so the file can be used as a debugger command 
procedure without modification. Thus, if a lengthy debugging session is 
interrupted, you can execute the log file as you would any other debugger 
command procedure. Executing the log file restores the debugging session 
to the point at which it was previously terminated. 


To create a debugger log file, use the command SET OUTPUT LOG. By 
default, the debugger writes the log to SYS$DISK:[ JDEBUG.LOG. To 
name a debugger log file, use the SET LOG command. You can 
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override any field of the default file specification. For example, after you 
enter the following commands, the debugger logs the session to the file 
[JONES.WORK2|MONITOR.LOG: 


DBG> SET LOG [JONES .WORK2]MONITOR 
DBG> SET OUTPUT LOG 


You might want to enter the SET OUTPUT LOG command in your 
debugger initialization file (see Section 8.2). 


The SHOW LOG command reports whether the debugger is writing to a 
log file and identifies the current log file. The SHOW OUTPUT command 
identifies all current output options. 


If you are debugging in screen mode, the SET OUTPUT SCREEN_LOG 
command enables you to log the screen contents as the screen is updated. 
To use this command, you must already be logging your debugging 
session—that is, the command SET OUTPUT SCREEN_LOG is valid 
only after you have entered the command SET OUTPUT LOG. Note that 
using SET OUTPUT SCREEN_LOG is not desirable for a long debugging 
session, because storing screen information in this manner results in a big 
log file. For other techniques on saving screen-mode information, see also 
the descriptions of the commands SAVE and EXTRACT in Chapter 7 and 
in the command dictionary. 


If you plan to use a log file as a command procedure, you should first enter 
the command SET OUTPUT VERIFY so that debugger commands are 
echoed as they are read. 


8.4 Defining Symbols for Commands, Address Expressions, and Values 
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The DEFINE command enables you to create a symbol for a lengthy or 
often-repeated command sequence or address expression and to store the 
value of a language expression in a symbol. 


You specify the kind of symbol you want to define by the command 


qualifier you use with the DEFINE command (/COMMAND, /ADDRESS, 
or /VALUE). The default qualifier is /ADDRESS. If you plan to enter 
several DEFINE commands with the same qualifier, you can first use the 
SET DEFINE command to establish a new default qualifier (for example, 
SET DEFINE COMMAND makes the DEFINE command behave like 
DEFINE/COMMAND). The SHOW DEFINE command identifies the 
default qualifier currently in effect. 


Use the SHOW SYMBOL/DEFINED command to identify symbols you 
have defined with the DEFINE command. Note that the SHOW SYMBOL 
command without the /DEFINED qualifier identifies only the symbols that 
are defined in your program, such as the names of routines and variables. 


Use the DELETE command to DELETE symbol definitions created with 
the DEFINE command. 


When defining a symbol within a command procedure, use the /LOCAL 
qualifier to confine the symbol definition to that command procedure. 


Additional Convenience Features 
8.4 Defining Symbols for Commands, Address Expressions, and Values 


8.4.1. Defining Symbols for Commands 


Use the DEFINE/COMMAND command to equate one or more commands 
(actually, strings) to a shorter symbol. The basic syntax is illustrated in 
the following example. 


DBG> DEFINE/COMMAND SB = "SET BREAK" 
DBG> SB PARSER 


In the example, the DEFINE/COMMAND command equates the symbol 
SB to the string SET BREAK (note the use of the quotation marks to 
delimit the command string). When the command line SB PARSER is 
executed, the debugger substitutes the string SET BREAK for the symbol 
SB and then executes the SET BREAK command. 


In the following example, the DEFINE/COMMAND command equates 
the symbol BT to the string consisting of the command SHOW BREAK 
followed by the command SHOW TRACE (use semicolons to separate 
multiple command strings): 


DBG> DEFINE/COMMAND BT = "SHOW BREAK;SHOW TRACE" 
The SHOW SYMBOL/DEFINED command identifies the symhol BT as 
follows: 


DBG> SHOW SYM/DEFINED BT 

defined BT 
bound to: "SHOW BREAK;SHOW TRACE" 
was defined /command 

DBG> 


To define complex commands, you might need to use command procedures 
with parameters (see Section 8.1.2 for information about passing 
parameters to command procedures). For example: 


DBG> DEFINE/COMMAND DUMP = "@DUMP_PROG2.COM" 


8.4.2 Defining Symbols for Address Expressions 


Use the DEFINE/ADDRESS command to equate an address expression to 
a symbol. Although /ADDRESS is the default qualifier for the DEFINE 
command, it is used in the following examples for emphasis. 


In the following example, the symbol B1 is equated to the address of line 
378; the command SET BREAK B1 then sets a breakpoint on line 378. 


DBG> DEFINE/ADDRESS Bl = %SLINE 378 
DBG> SET BREAK Bl 


The DEFINE/ADDRESS command is useful when you need to specify a 
long path name repeatedly to reference the name of a variable or routine 
that is defined multiple times. In the next example, the symbol UX is 
equated to the path name SCREEN_IO\ UPDATE\X; the abbreviated 
command line EXAMINE UX can then be used to obtain the value of X in 
routine UPDATE of module SCREEN_IO. 


DBG> DEFINE UX = SCREEN_IO\UPDATE\X 
DBG> EXAMINE UX 
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8.4.3. Defining Symbols for Values 


Use the DEFINE/VALUE command to equate the current value of a 
language expression to a symbol (the current value is the value at the 
time the DEFINE/VALUE command was entered). 


The following example illustrates how the DEFINE/VALUE command can 
be used to count the number of calls to a routine. 


DBG> DEFINE/VALUE COUNT = 0 
DBG> SET TRACE/SILENT ROUT DO (DEFINE/VALUE COUNT = COUNT + 1) 
DBG> GO 


DBG> EVALUATE COUNT 
14 
DBG> 


In the example, the first DEFINE/VALUE command initializes the value 
of the symbol COUNT to 0. The SET TRACE command sets a silent 
tracepoint on routine ROUT and (through the DO clause) increments 

the value of COUNT by 1 every time ROUT is called. After execution is 
resumed and eventually suspended, the EVALUATE command obtains the 
current value of COUNT (the number of times that ROUT was called). 


8.5 Assigning Commands to Function Keys 


To facilitate entering commonly used commands, the function keys on the 
keypad have predefined debugger functions that are established when you 
invoke the debugger. These predefined functions are identified in detail 
in Appendix B. You can modify the functions of the keypad keys to suit 
your individual needs. If you have a VT200- or VT300-series terminal or a 
workstation, you can also bind commands to the additional function keys 
on the LK201 keyboard. 


The debugger commands DEFINE/KEY, SHOW KEY, and DELETE/KEY 
enable you to assign, identify, and delete key definitions, respectively. 
Before you can use this feature, keypad mode must be enabled with the 
SET MODE KEYPAD command (keypad mode is enabled by default). 
Keypad mode also enables you to use the predefined functions of the 
keypad keys. 


If you want to use the keypad keys to enter numbers rather than debugger 
commands, enter the command SET MODE NOKEYPAD. 


8.5.1 Basic Conventions 
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The debugger DEFINE/KEY command, which is similar to the DCL 
DEFINE/KEY command, enables you to assign a string to a function key. 
In the following example, the DEFINE/KEY command defines keypad key 
7 to enter and execute the command SHOW MODULE *: 


DBG> DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 
%DEBUG-I-DEFKEY, DEFAULT key KP7 has been defined 
DBG> 


Additional Convenience Features 
8.5 Assigning Commands to Function Keys 


The /TERMINATE qualifier indicates that pressing key 7 executes the 
command. You do not have to press Return after pressing key 7. 


KP7 is the key name that you must use with the commands DEFINE/KEY, 
SHOW KEY, and DELETE/KEY. The valid key names that you can use 
with these commands are listed in the command dictionary for VT52 

and VT100-series terminals and for LK201 keyboards (see the command 
descriptions). 


The same function key can be assigned any number of definitions as long 
as each definition is associated with a different state. The predefined 
states (DEFAULT, GOLD, BLUE, and so on) are identified in Appendix B. 
In the preceding example, the informational message indicates that key 7 
has been defined for the DEFAULT state (which is the default key state). 


You can enter key definitions in a debugger initialization file (see 
Section 8.2) so that these definitions are available whenever you invoke 
the debugger. 


To display a key definition in the current state, enter the command SHOW 
KEY. For example: 


DBG> SHOW KEY KP7 


DEFAULT keypad definitions: 
KP7 = "SHOW MODULE *" (echo,terminate,nolock) 
DBG> 


To display a key definition in a state other than the current state, specify 
that state with the /STATE qualifier when entering the SHOW KEY 


command. To see all key definitions in the current state, enter the 
command SHOW KEY/ALL. 


To delete a key definition, use the DELETE/KEY command. To delete a 
key definition in a state other than the current state, specify that state 
with the /STATE qualifier. For example: 


DBG> DELETE/KEY/STATE=GOLD KP7 
SDEBUG-I-DELKEY, GOLD key KP7 has been deleted 
DBG> 


8.5.2 Advanced Techniques 


This section illustrates more advanced techniques for defining keys, 
particularly techniques related to the use of state keys. 


The following command line assigns the unterminated command string 
"SET BREAK %LINE" to keypad key 9, for the BLUE state. 


DBG> DEFINE/KEY/IF STATE=BLUE KP9 "SET BREAK %LINE" 


The predefined DEFAULT key state is established by default. The 
predefined BLUE key state is established by pressing keypad key PF4. 
You would enter the command line assigned in the preceding example 
(SET BREAK %LINE ... ) by pressing key PF4 then key 9, then entering 
a line number, then pressing the Return key to terminate and process the 
command line. 
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8.6.1 


8.6.2 


Additional Convenience Features 
8.5 Assigning Commands to Function Keys 


The SET KEY command enables you to change the default state for 

key definitions. For example, after entering the command SET KEY 
/STATE=BLUE, you would not need to press PF4 to enter the command © 
line in the previous example. Also, the SHOW KEY command would show 
key definitions in the BLUE state, by default, and the DELETE/KEY 
command would delete key definitions in the BLUE state by default. 


You can create additional key states. For example: 


DBG> SET KEY/STATE=DEFAULT 
DBG> DEFINE/KEY/SET STATE=RED/LOCK STATE F12 "" 


In this example, the SET KEY command establishes DEFAULT as the 
current state. The DEFINE/KEY command makes key F12 (LK201 
keyboard) a state key. As a result, pressing F12 while in the DEFAULT 
state causes the current state to become RED. The key definition is not 
terminated and has no other effect (a null string is assigned to F12). After 
pressing F12, you can enter "RED" commands by pressing keys that have 
definitions associated with the RED state. 


Using Control Structures to Enter Commands 


The FOR, IF, REPEAT, and WHILE commands enable you to create 
looping and conditional constructs for entering debugger commands. 
The associated command EXITLOOP is used to exit a FOR, REPEAT, or 
WHILE loop. 


See Section 4.1.5 and Section 9.3.2.2 for information about evaluating 
language expressions. 


FOR Command 
The FOR command executes a sequence of commands while incrementing 
a variable a specified number of times. It has the following format: 

FOR name=expressioni TO expression2 [BY expression3] DO(command[; ..._ }) 
For example, the following command line sets up a loop that initializes the 
first 10 elements of an array to zero: 
DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 

IF Command 
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The IF command executes a sequence of commands if a language 
expression (Boolean expression) is evaluated as true. It has the following 
format: 


IF boolean-expression THEN (command[;... ]) [ELSE (command[;... ])] 


The following FORTRAN example sets up a condition that issues the 
command EXAMINE X2 if X1 is not equal to —9.9, and issues the 
command EXAMINE Y1 otherwise: 


DBG> IF Xl .NE. -9.9 THEN (EXAMINE X2) ELSE (EXAMINE Y1) 


Additional Convenience Features 
8.6 Using Control Structures to Enter Commands 


The following Pascal example combines a FOR loop and a condition test. 
The STEP command is issued if X1 is not equal to —9.9. The test is made 
four times: 


DBG> FOR COUNT = 1 TO 4 DO (IF X1 <> ~-9.9 THEN (STEP) ) 


8.6.3 REPEAT Command 


The REPEAT command executes a sequence of commands a specified 
number of times. It has the following format: 


REPEAT language-expression DO (command; ..._ J) 


For example, the following command line sets up a loop that issues a 
sequence of two commands (EXAMINE Y then STEP) 10 times: 


DBG> REPEAT 10 DO (EXAMINE Y; STEP) 


8.6.4 WHILE Command 


The WHILE command executes a sequence of commands while the 
language expression (Boolean expression) you have specified evaluates 
as true. It has the following format: 


WHILE boolean-expression DO (command[;..._ ]) 


_ The following Pascal example sets up a loop that tests X1 and X2 
repetitively and issues the two commands EXAMINE X2 and STEP if 
X2 is less than X1: 


DBG> WHILE X2 < X1 DO (EX X2;STEP) 


8.6.5 EXITLOOP Command 


The EXITLOOP command exits one or more enclosing FOR, REPEAT, or 
WHILE loops. It has the following format: 


EXITLOOP [n] 
The integer n specifies the number of nested loops to exit from. 


The following Pascal example sets up an endless loop that issues a STEP 
command with each iteration. After each step, the value of X is tested. If 
X is greater than 3, the EXITLOOP command terminates the loop. 


DBG> WHILE TRUE DO (STEP; IF X > 3 THEN EXITLOOP) 


8.7 Calling Routines Independently of Program Execution 


The CALL command enables you to execute a routine independently of 
the normal execution of your program. It is one of the four debugger 
commands that can be used to execute your program (the others are GO, 
STEP, and EXIT). 
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The CALL command executes a routine whether or not your program 
actually includes a call to that routine, so long as the routine was linked 
with your program. Thus you can use the CALL command to execute 
routines for any purpose (for example, to debug a routine out of the 
context of program execution, invoke a run-time library procedure, execute 
a routine that dumps debugging information, and so on). 


You can debug unrelated routines by linking them with a dummy main 
program that has a transfer address, and then using the CALL command 
to execute them. 


The following example shows how you could use the CALL command to 
display some process statistics without having to include the necessary 
code in your program. The example consists of calls to run-time library 
routines that initialize a timer (LIB$INIT_TIMER) and display the elapsed 
time and various statistics (LIBSSHOW_TIMER). (Note that the presence 
of the debugger affects the timings and counts): 


DBG> SET MODULE SHARESLIBRTL @ 
DBG> CALL LIBS$INIT TIMER 


value returned is 1 © 
DBG> [enter various debugger commands] 


DBG> CALL LIBSSHOW TIMER @O 


ELAPSED: O 00:00:21.65 CPU: 0:14:00.21 BUFIO: 16 DIRIO: 0 FAULTS: 3 
value returned is 1 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ Routines LIB$INIT_TIMER and LIB$SHOW_TIMER are in the 
shareable image LIBRTL. This image must be set by setting its 
"module" because only its universal symbols are accessible during a 
debugging session (see Section 5.4.2.3). 


@ This CALL command executes routine LIB$INIT_TIMER. 


© The "value returned" message indicates the value returned in register 
RO after the CALL command has been executed. 


By VMS convention, after a called routine has executed, register RO 
contains the function return value (if the routine is a function) or the 
procedure completion status (if the routine is a procedure that returns 
a status value). If a called procedure does not return a status value or 
function value, the value in RO might be meaningless, and the "value 
returned" message can be ignored. 


@ This CALL command executes routine LIB$SHOW_TIMER. 


The following example shows how to call LIB${SHOW_VM (also in 
LIBRTL) to display memory statistics. (Again, note that the presence 
of the debugger affects the counts): 


DBG> SET MODULE SHARESLIBRTL 
DBG> CALL LIBSSHOW VM 
1785 calls to LIBSGET_VM, 284 calls to LIBSFREE VM, 122216 bytes still allocated 
value returned is 1 
DBG> 
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Additional Convenience Features 
8.7 Calling Routines Independently of Program Execution 


You can pass parameters to routines with the CALL command. See the 
description of the CALL command in the command dictionary for details 
and examples. 
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9 Debugging Special Cases 


This chapter presents debugging techniques for special cases that are not 
covered elsewhere in this manual: 


¢ Optimized code 

e Screen-oriented programs 

e Multilanguage programs 

e Exceptions and condition handlers 
e Exit handlers 

e AST-driven programs 


9.1 Debugging Optimized Code 


By default, many compilers optimize the code they produce so that the 
program executes faster. The net result is that the code that is executing 
as you debug might not match the source code displayed in a screen-mode 
source display (see Section 7.2.1) or in a source listing file. For example, 
some optimization techniques eliminate variables so that you no longer 
have access to them while debugging. 


To avoid the problems of debugging optimized code, many compilers allow 
you to specify the /NOOPTIMIZE (or equivalent) command qualifier at 
compile time. Specifying this qualifier inhibits most compiler optimization, 
thereby reducing discrepancies between the source code and executable 
code caused by optimization. 


If this option is not available to you, read this section. It describes the 
techniques for debugging optimized code and gives some typical examples 
of optimized code to illustrate the potential causes of confusion. 


When debugging optimized code, use a screen-mode instruction display, 
such as the predefined display INST, to show the decoded VAX assembly- 
language instruction stream of your program (see Section 7.2.4). An 
instruction display shows the exact code that is executing. 


In screen mode, pressing keypad key 7 places the SRC and INST displays 
side by side for easy comparison. Alternatively, you can inspect a compiler- 
generated machine code listing. 


In addition, to execute the program at the instruction level and examine 
instructions, use the techniques described in Section 4.3. 


Using these methods, you should be able to determine what is happening 
at the executable code level and thereby resolve the discrepancy between 
source display and program behavior. 
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Eliminated Variables 
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A compiler might optimize code by eliminating variables, either 
permanently or temporarily at various points during execution. If 

you try to examine a variable X that no longer is accessible because of 
optimization, the debugger might display one of the following messages: 


%S“DEBUG-W-UNALLOCATED, entity X was not allocated in memory 
(was optimized away) 


SDEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC (was optimized away) 


The following Pascal example shows how this could happen. 


PROGRAM DOC (OUTPUT) ; 


VAR 

X,Y: INTEGER; 
BEGIN 

X := 5; 

Y := 2; 

WRITELN (X*Y) ; 
END. 


If you compile this program with the /NOOPTIMIZE (or equivalent) 
qualifier, you obtain the following (normal) behavior when debugging: 


$ PASCAL/DEBUG/NOOPTIMIZE DOC 
$ LINK/DEBUG DOC 


$ RUN DOC 

DBG> STEP 

stepped to DOC\%LINE 5 
So: x 2S 03 

DBG> STEP 

stepped to DOC\%LINE 6 
6: Yo 4= 23 

DBG> STEP 

stepped to DOC\%LINE 7 
af WRITELN (X*Y) ; 

DBG> EXAMINE X,Y 

DOGC\X:. 5 

DOC\Y*s: <2 

DBG> 


If you compile the program with the /OPTIMIZE (or equivalent) qualifier, 
because the values of X and Y are not changed after the initial assignment, 
the compiler calculates X*Y, stores that value (10), and does not allocate 
storage for X or Y. Therefore, after you invoke the debugger, a STEP 
command takes you directly to line 7 rather than line 5. Moreover, you 
cannot examine X or Y: 


Debugging Special Cases 
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$ PASCAL/DEBUG/OPTIMIZE DOC 
$ LINK/DEBUG DOC 
$ RUN DOC 


DBG> EXAMINE X,Y 
SDEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC (was optimized away) 


DBG> STEP 
stepped to DOC\%SLINE 7 

oa WRITELN (X*Y) ; 
DBG> 


To see what values are being used in your optimized program, use the 
command EXAMINE/OPERAND .%PC to display the machine code at 
the current PC value, including the values and symbolization of all of the 
operands. For example, the following lines show the optimized code when 
the PC value is at the WRITELN statement: 


DBG> STEP 
stepped to DOC\%LINE 7 
7: WRITELN (X*Y) ; 
DBG> EXAMINE/OPERAND .%PC 
DOC\SLINE 7: PUSHL S*#10 
DBG> 
In contrast, the following lines show the unoptimized code at the 
WRITELN statement: 
DBG> STEP 
stepped to DOC\S%SLINE 7 
7: WRITELN (X*Y) ; 
DBG> EXAMINE/OPERAND .%PC 
DOC\SLINE 7: MOVL S*#10,B*-4 (FP) 
B*-4 (FP) 2146279292 contains 62914576 
DBG> 


9.1.2 Changes in Coding Order 


Several methods of optimizing consist of performing operations in a 
sequence different from the sequence specified in the source code. 
Sometimes code is eliminated altogether. 


As a result, the source code displayed by the debugger does not correspond 
exactly to the actual code being executed. 


To illustrate, the following example depicts a segment of source code from 
a FORTRAN program as it might appear on a compiler listing or in a 
screen-mode source display. This code segment sets the first ten elements 
of array A to the value 1/X. 


Line ‘Source Code 
5 DO 100 I=1,10 
6 A(T) = 1/X 
7 100 CONTINUE 
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9.1.3 Use of Registers 
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As the compiler processes the source program, it determines that the 
reciprocal of X need only be computed once, not ten times as the source 
code specifies, because the value of X never changes in the DO-loop. The 
compiler thus generates optimized code equivalent to the following code 
segment: 


Line Optimized Code Equivalent 
5 TEMP = 1/X 
DO 100 I=1,10 
6 A(I) = TEMP 
7 100 CONTINUE 


In the optimized code, the value of 1/X is computed once, saved in a 
temporary location, and then assigned to each A(I). The optimized code 
now executes faster, but it no longer corresponds exactly to the source 
code. 


In this example, if you execute to line 5 by entering a STEP command, the 
debugger displays the source line as it appears in the source file, not the 
optimized code equivalent that it is actually executing. 


stepped to PROG _\%LINE 5 
a: DO 100 I=1,10 


At this point, if you enter another STEP command to execute line 5, the 
debugger executes line 5 of the optimized code, not line 5 of the displayed 
source code. Thus, the program computes the reciprocal of X and sets up 
the DO loop, whereas the source display indicates only that the DO loop is 
set up. 


This discrepancy is not obvious from looking at the displayed source line. 
Furthermore, if the computation of 1/X were to fail because X is zero, it 
would appear from inspecting the source display that a division by zero 
had occurred on a source line that contains no division at all. 


This kind of apparent mismatch between source code and executable code 
should be expected from time to time when debugging optimized programs. 
It can be caused not only by code motions out of loops, as in the previous 
example, but by a number of other optimization methods as well. 


A compiler might determine that the value of an expression does not 
change between two given occurrences and might save the value in a 
register. In such cases, the compiler does not recompute the value for the 
next occurrence, but assumes the value saved in the register is valid. 


If, while debugging a program, you use the DEPOSIT command to change 
the value of the variable in the expression, the corresponding value stored 
in the register might not be changed. Thus, when execution continues, the 
value in the register might be used instead of the changed value in the 
expression, causing unexpected results. 


In addition, when the value of a nonstatic variable (see Section 3.6.2) is 
held in a register, its value in memory is generally invalid; therefore, a 
spurious value might be displayed if you enter the EXAMINE command 
for a variable under these circumstances. 
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9.1.4 Use of Condition Codes 


One optimization technique takes advantage of the way in which the VAX 
processor condition codes are set. For example, consider the following 
Pascal source code: 

A232. t 
ph ame Gee a6) 
THEN 


aS 


Rather than test the new value of X to determine whether to branch, the 
optimized code bases its decision on the condition code setting after 2.5 is 
added to X. Thus, if you attempt to set a breakpoint on the IF statement 
and deposit a different value into X, you do not achieve the intended result 
because the condition codes no longer reflect the value of X. In other words, 
the decision to branch is being made without regard to the deposited value 
of the variable. 


Again, you can use the command EXAMINE/OPERAND .%PC to 
determine the correct location for depositing so as to achieve the desired 
effect. 


9.2 Debugging Screen-Oriented Programs 


The debugger uses the terminal screen for input and output (J/O) during a 
debugging session. If you use a single terminal to debug a screen-oriented 
program that uses most or all of the screen, debugger I/O can overwrite, or 
can be overwritten by, program I/O. 


Using one terminal for both program I/O and debugger I/O is even more 
complicated if you are debugging in screen mode and your screen-oriented 
program calls any VMS RTL Screen Management (SMG$) routines. This 
is because the debugger’s screen mode also calls SMG routines. In such 
cases, the debugger and your program share the same SMG pasteboard, 
causing further interference. 


To avoid these problems when debugging a screen-oriented program, use 
one of the following techniques to separate debugger I/O from program I/O: 


e If you are at a workstation running VWS, start your debugging session 
and then enter the debugger command SET MODE SEPARATE. 
It creates a separate terminal-emulator window for debugger I/O. 
Program I/O continues to be displayed in the window from which you 
invoked the debugger. 


e If you are at a workstation running DECwindows and want to display 
the debugger’s DECwindows interface on a separate workstation (also 
running DECwindows), see Section 1.6.3.1. 


e If you are at a workstation running DECwindows but want to use the 
debugger’s command interface rather than the DECwindows interface, 
see Section 1.6.3.3. It explains how to create a separate DECterm 
window for debuger I/O. The effect is similar to using the command 
SET MODE SEPARATE on a workstation running VWS. 
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If you do not have a workstation, use two terminals—one for program 
I/O and another for debugger I/O. The technique is described in the 
rest of this section. 


Assume that TTD1: is your current terminal, from which you plan to 
invoke the debugger. You want to display debugger I/O on terminal TTD2: 
so that TTD1: is devoted exclusively to program I/O. 


Follow these steps: 


1 


Provide the necessary protection to TTD2: so that you can allocate 
that terminal from TTD1: (see Section 9.2.1). 


The remaining steps are all performed from TTD1:. 


Allocate TTD2:. This provides your process on TTD1: with exclusive 
access to TTD2:: 


S$ ALLOCATE TTD2: 


Assign the debugger logical names DBG$INPUT and DBG$OUTPUT 
to TTD2:: 


S$ DEFINE DBGSINPUT TTD2: 
S$ DEFINE DBGSOUTPUT TTD2: 


DBG$INPUT and DBG$OUTPUT specify the debugger input device 
and output device, respectively. By default, these logical names are 
equated to SYS$INPUT and SYS$OUTPUT, respectively. Assigning 
DBG$INPUT and DBG$OUTPUT to TTD2: enables you to display 

debugger commands and debugger output on TTD2:. 


Make sure that the terminal type is known to the system. Use the 
following command: 


S SHOW DEVICE/FULL TTD2: 


If the device type is "unknown," your system manager (or a user with 
LOG_IO or PHY_IO privilege) must make it known to the system 

as shown in the following example. In the example, the terminal is 
assumed to be a VT200: 


$ SET TERMINAL/PERMANENT/DEVICE=VT200 TTD2: 
Run the program to be debugged: 

$ RUN FORMS 

You can now observe debugger I/O on TTD2: 


When finished with the debugging session, deallocate TTD2: as follows 
(or log out): 


S DEALLOCATE TTD2: 


Debugging Special Cases 
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9.2.1. Setting the Protection to Allocate a Terminal 


On a properly secured system, terminals are protected so that you cannot 
allocate a terminal from another terminal. 


To set the nessary protection, your system manager (or a user with the 
privileges indicated) should follow the steps illustrated in the following 
example. 


In the example, TTD1: is your current terminal (from which you plan to 
invoke the debugger), and TTD2: is the terminal to be allocated so that it 
can display debugger I/O. 


1 Ifboth TTD1: and TTD2: are hardwired to the system, go to Step 4. 


If TTD1: and TTD2: are connected to the system over a LAT (local 
area transport), continue with Step 2. 


Log in to TTD2: 
Enter these commands (you need LOG_IO or PHY_IO privilege): 


$ SET PROCESS/PRIV=LOG_ IO 
S$ SET TERMINAL/NOHANG/PERMANENT 
S$ LOGOUT/NOHANG 


4 Enter one of the following commands (you need OPER privilege): 


S SET ACL/OBJECT TYPE=DEVICE/ACL= (IDENT=[PROJ, JONES],ACCESS=READ+WRITE) TTD2: @ 
$ SET PROTECTION=WORLD:RW/DEVICE TTD2: 2 


@ The SET ACL command line is preferred because it uses an access 
control list (ACL). In the example, access is restricted to UIC 
[PROJ,JONES]. 


@ The SET PROTECTION command line provides world read/write 
access and, therefore, allows any user to allocate and perform I/O 
to TTD2:. 





9.3 Debugging Multilanguage Programs 


The debugger enables you to debug modules whose source code is written 
in different languages, within the same debugging session. This section 
highlights some language specific behavior that you should be aware of, to 
minimize possible confusion. 


When debugging in any language, be sure to consult the documentation 
supplied with that language. The chapter devoted to debugging, in 

the user’s guide, contains all language dependent information for that 
language. See also Appendix E of this manual, which tabulates the 
constructs and operators that are supported by the debugger for each 
language. 
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9.3.1 Controlling the Current Debugger Language 


At debugger startup, the debugger sets the current language to that in 
which the module containing the main program (usually the routine 
containing the image transfer address) is written. The current language is 
identified when you invoke the debugger. For example: 


$ RUN FORMS 
VAX DEBUG Version 5.4 


S$DEBUG-I-INITIAL, language is PASCAL, module set to FORMS 
DBG> 


The current language setting determines how the debugger parses and 
interprets the names, operators, and expressions you specify in debugger 
commands, including things like the typing of variables, array and record 
syntax, the default radix for integer data, case sensitivity, and so on. 
The language setting also determines how the debugger displays data 
associated with your program. 


Many programs include modules that are written in languages other than 
that of the main program. To minimize confusion, by default the debugger 
language remains set to the language of the main program throughout a 
debugging session, even if execution is suspended within a module written 
in another language. 


To take full advantage of symbolic debugging with such modules, use 

the SET LANGUAGE command to set the debugging context to that 

of another language. For example, the following command causes the 
debugger to interpret any symbols, expressions, and so on according to the 
rules of the COBOL language: 


DBG> SET LANGUAGE COBOL 


The keywords that you can use with the SET LANGUAGE command 
correspond to all of the VMS supported languages that are also supported 
by the debugger: 


ADA 
BASIC 
BLISS 

C 
COBOL 
DIBOL 
FORTRAN 
MACRO 
PASCAL 
PLI 
RPG 
SCAN 


In addition, when debugging a program that is written in an unsupported 
language, you can specify the command SET LANGUAGE UNKNOWN. To 
maximize the usability of the debugger with unsupported languages, the 
SET LANGUAGE UNKNOWN command causes the debugger to accept 

a large set of data formats and operators, including some that might be 
specific to only a few supported languages. The operators and constructs 
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that are recognized when the language is set to UNKNOWN are identified 
in Appendix E. 


9.3.2 Specific Differences Among Languages 


This section lists some of the differences you should keep in mind when 
debugging in various languages. Included are differences that are affected 
by the SET LANGUAGE command and other differences (for example, 
language specific initialization code and predefined breakpoints). 


This list is not intended to be complete. Consult your language 
documentation for complete details. 


9.3.2.1. Default Radix 
The default radix for entering and displaying integer data is hexadecimal 
for BLISS and MACRO and decimal for all other languages. 


Use the SET RADIX command to establish a new default radix. 


9.3.2.2 Evaluating Language Expressions 
Several debugger commands and constructs evaluate language 


expressions: 
¢ The EVALUATE, DEPOSIT, IF, FOR, REPEAT, and WHILE 
commands. 


¢ WHEN clauses, which are used with the SET BREAK, SET TRACE, 
and SET WATCH commands. 


When processing these commands, the debugger evaluates language 
expressions in the syntax of the current language and in the current radix 
as discussed in Section 4.1.5. 


Note that operators vary widely among different languages (see 
Appendix E). For example, the following two commands evaluate 
equivalent expressions in Pascal and FORTRAN, respectively: 


DBG> SET WATCH X WHEN (Y < 5) ! Pascal 
DBG> SET WATCH X WHEN (Y .LT. 5) ! FORTRAN 


Assume that the language is set to PASCAL and you have entered the 
first (Pascal) command. You now step into a FORTRAN routine, set the 
language to FORTRAN, and resume execution. While the language is set 
to FORTRAN, the debugger is not able to evaluate the expression (Y < 5). 
As a result, it sets an unconditional watchpoint and, when the watchpoint 
is triggered, returns a syntax error for the "<" operator. 


This type of discrepancy can also occur if you use commands that evaluate 
language expressions in debugger command procedures and initialization 
files. 


Note also that the debugger processes language expressions that contain 
variable names (or other address expressions) differently when the 
language is set to BLISS than when it is set to another language. See 
Section 4.1.5 for details. 
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9.3.2.3 Arrays and Records 


The syntax for denoting array elements and record components (if 
applicable) varies among languages. 


For example, some languages use brackets, [], and others use parentheses, 
(), to delimit array elements. 


Some languages (like BASIC) have zero-based arrays. Some languages 
have one-based arrays, as in the following example: 


DBG> EXAMINE INTEGER ARRAY 
PROG2\ INTEGER ARRAY 


Clete ee a 

(152) 3 31 

(1,3) % 12 

(25-1). LS 

(2,2): 22 

(Zys)es 18 
DBG> 


For some languages (like Pascal and Ada) the specific array declaration 
determines how the array is based. 


9.3.2.4 Case Sensitivity 


Names and language expressions are case sensitive in C. You must specify 
them exactly as they appear in the source code. For example, the following 
two commands are not equivalent when the language is set to C: 


DBG> SET BREAK SCREEN _IO\$LINE 10 
DBG> SET BREAK screen _io\%LINE 10 


Initialization Code 


If you have a multilanguage program that includes an Ada package, 
or a FORTRAN main program that was compiled with the 
/CHECK=UNDERFLOW (or /CHECK=ALL) qualifier, a NOTATMAIN 
message is issued when you invoke the debugger. For example: 


$ RUN MONITOR 
VAX DEBUG Version 5.4 


S$DEBUG-I-INITIAL, language is ADA, module set to MONITOR 
S$DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 


~The NOTATMAIN message indicates that execution is suspended before 


the beginning of the main program. This enables you to execute and check 
some initialization code under debugger control. 


The initialization code is created by the compiler and is placed in a special 
PSECT named LIB$INITIALIZE. In the case of an Ada package, the 
initialization code belongs to the package body (which might contain 
statements to initialize variables, and so on). In the case of a FORTRAN 
program, the initialization code declares the handler that is needed if you 
specify the /CHECK=UNDERFLOW or /CHECK=ALL qualifier. 
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The NOTATMAIN message indicates that, if you do not want to debug the 
initialization code, you can execute immediately to the beginning of the 
main program by entering a GO command. You are then at the same point 
as when you invoke the debugger with any other program. Entering the 
GO command again starts program execution. 


9.3.2.6 Ada Predefined Breakpoints 
If your program is linked with a module that is written in Ada, two 
breakpoints that are associated with Ada tasking exception events are 
automatically established when you invoke the debugger. Note that these 
breakpoints are not affected by a SET LANGUAGE command. They are 
established automatically during debugger initialization when the Ada 
Run-Time Library is present. When you enter a SHOW BREAK command 
under these conditions, the following breakpoints are displayed: 


DBG> SHOW BREAK 

Predefined breakpoint on ADA event "DEPENDENTS EXCEPTION" for any value 
Predefined breakpoint on ADA event "EXCEPTION TERMINATED" for any value 
DBG> 


Debugging Exceptions and Condition Handlers 


A condition handler is a procedure that the VMS operating system 
executes when an exception occurs. 


Exceptions include hardware conditions (such as an arithmetic overflow or 
a memory access violation) or signaled software exceptions (for example, 
an exception signaled because a file could not be found). 


VMS conventions specify how, and in what order, various condition 
handlers established by the operating system, the debugger, or your 
own program are invoked—for example, the primary handler, call 
frame (application-declared) handlers, and so on. Section 9.4.3 describes 
condition handling when you are using the debugger. See the VMS Run- 
Time Library Routines Volume for additional general information about 
condition handling. 


Tools for debugging exceptions and condition handlers include the 
following: 


e The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION 
commands, which direct the debugger to treat any exception generated 
by your program as a breakpoint or tracepoint, respectively (see 
Section 9.4.1 and Section 9.4.2). 


e Several built-in symbols (such as %EXC_NAME), which enable you to 
qualify exception breakpoints and tracepoints (see Section 9.4.4). 


e The SET BREAK/EVENT and SET TRACE/EVENT commands, which 
enable you to break on or trace exception events that are specific to 
Ada and SCAN programs (see the corresponding documentation for 
more information). 
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Setting Breakpoints or Tracepoints on Exceptions 


When you enter a SET BREAK/EXCEPTION (or SET TRACE 
/EXCEPTION) command, you direct the debugger to treat any exception 
generated by your program as a breakpoint (or tracepoint). As a result 
of a SET BREAK/EXCEPTION command, if your program generates an 
exception, the debugger suspends execution, reports the exception and 
the line where execution is suspended, and prompts for commands. The 
following example illustrates the effect: 


DBG> SET BREAK/EXCEPTION 
DBG> GO 


SSYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0Q000066C, PSL=03C00022 
break on exception preceding TEST\SLINE 13 

6: KX oS: 37 Ye 
DBG> 


Note that an exception breakpoint (or tracepoint) is triggered even if 
your program has a condition handler to handle the exception. The 

SET BREAK/EXCEPTION command causes a breakpoint to occur before 
any handler can execute (and thereby possibly dismiss the exception). 
Without the exception breakpoint, the handler would be executed, and the 
debugger would get control only if no handler dismissed the exception (see 
Section 9.4.2 and Section 9.4.3). 


The following command line is useful for identifying where an exception 
occurred. It causes the debugger to display automatically the sequence of 
active calls and the PC value at an exception breakpoint. 


DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 


You can also create a screen-mode DO display that issues a SHOW CALLS 
command whenever the debugger interrupts execution. For example: 


DBG> DISPLAY CALLS DO (SET MODULE/CALLS; SHOW CALLS) 


An exception tracepoint (established with the SET TRACE/EXCEPTION 
command) is like an exception breakpoint followed by a GO command 
without an address expression specified. 


An exception breakpoint cancels an exception tracepoint, and vice versa. 


To cancel exception breakpoints or tracepoints, use the CANCEL BREAK 
/EXCEPTION or CANCEL TRACE/EXCEPTION command, respectively. 


Resuming Execution at an Exception Breakpoint 


When an exception breakpoint is triggered, execution is suspended before 
any application-declared condition handler is invoked. When you resume 
execution from the breakpoint with the GO, STEP, or CALL commands, 
the behavior is as follows: 


e Entering a GO command without an address-expression parameter, 
or entering a STEP command, causes the debugger to resignal the 


9-12 


DBG> SET BREAK/EXCEPTION 
DBG> GO 


Debugging Special Cases 
9.4 Debugging Exceptions and Condition Handlers 


exception. The GO command enables you to observe which application- 
declared handler, if any, next handles the exception. The STEP 
command causes you to step into that handler (see the next example). 


e Entering a GO command with an address-expression parameter causes 
execution to resume at the specified location, thus inhibiting the 
execution of any application-declared handlers. 


¢ Acommon debugging technique at an exception breakpoint is to call 
a dump routine with the CALL command (see Chapter 8). When you 
enter the CALL command at an exception breakpoint, no breakpoints, 
tracepoints, or watchpoints that were previously set within the called 
routine are active, so that the debugger does not lose the exception 
context. After the routine has executed, the debugger prompts for 
input. Entering a GO or STEP command at this point causes the 
debugger to resignal the exception, as for the first bulleted item in this 
list. 


The following FORTRAN example shows how to determine the presence of 
a condition handler at an exception breakpoint and how a STEP command, 
entered at the breakpoint, enables you to step into the handler. 


At the exception breakpoint, the SHOW CALLS command indicates that 
the exception was generated during a call to routine SYS$QIOW: 


SSYSTEM-F~SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000 
break on exception preceding SYSSQIOW+6 


DBG> SHOW CALLS 


module name routine name line rel PC abs PC 
SYSSQIOW 00000006 V7FFEDEO06 
*EXCSMAIN EXCSMAIN 23 0000003B 0000063B 


DBG> 


The following SHOW STACK command indicates that no handler is 
declared in routine SYS$QIOW. However, one level down the call stack, 
routine EXC$MAIN has declared a handler named SSHAND: 


DBG> SHOW STACK 
Stack frame 0 (2146296644) 
condition handler: 0 


SPA: Q 
S: 0 
mask: “M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11> 
PSW: 0020 (hexadecimal) 
saved AP: 2146296780 
saved FP: 2146296704 
saved PC: EXCSMAIN\SLINE 25 
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stack frame 1 (2146296704) 
condition handler: SSHAND 


SPA: 0 

> 0 

mask: “M<Ril> 

PSW: 0000 (hexadecimal) 
saved AP: 2146296780 
saved FP: 2146296760 
saved PC: SHARESDEBUG+2217 


DBG> 


At this exception breakpoint, entering a STEP command enables you to 
step directly into condition handler SSHAND: 


DBG> STEP 
stepped to routine SSHAND 
2s INTEGER*4 FUNCTION SSHAND (SIGARGS, MECHARGS) 
DBG> SHOW CALLS 
module name routine name line rel PC abs PC 
* SSHAND SSHAND 2 00000002 00000642 


----- above condition handler called with exception 0000045C: 


@SYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000 
saa end of exception message 


SYSSQIOW 00000006 T7FFEDE06 
*EXCSMAIN EXCSMAIN 23 0000003B 0000063B 
DBG> 


The debugger symbolizes the addresses of condition handlers into names if 
that is possible. However, note that with some languages, exceptions are 
first handled by an RTL routine, before any application-declared condition 
handler is invoked. In such cases, the address of the first condition 
handler might be symbolized to an offset from an RTL shareable image 
address. 


Effect of Debugger on Condition Handling 


When you run your program with the debugger, at least one of the 
following condition handlers is invoked, in the order given, to handle 
any exceptions caused by the execution of your program: 


1 Primary handler. 
2 Secondary handler. 


3  Call-frame handlers (application-declared). Also known as stack 
handlers. 


4 Final handler. 
5 Last-chance handler. 
6 Catchall handler. 


A handler can return one of the following three status codes to the VAX 
Condition Handling Facility: 


e SS$_RESIGNAL—The VMS operating system searches for the next 
handler. 


e¢ SS$ CONTINUE—The condition is assumed to be corrected, and 


execution continues. 
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e SS$ UNWIND—The call stack is unwound some number of frames, if 
necessary, and the signal is dismissed. 


For more information about condition handling, see the VMS Run-Time 
Library Routines Volume. 


9.4.3.1. Primary Handler 
When you run your program with the debugger, the primary handler is 
the debugger. Therefore, the debugger has the first opportunity to handle 
an exception, whether or not the exception is caused by the debugger 
(Section 3.7 describes how the debugger causes exceptions to occur in your 
program in order to control and monitor execution). 


If you have entered a SET BREAK/EXCEPTION or SET TRACE 
/EXCEPTION command, the debugger breaks on (or traces) any exceptions 
caused by your program. The break (or trace) action occurs before any 
application-declared handler is invoked. 


If you have not entered a SET BREAK/EXCEPTION or SET TRACE 
/EXCEPTION command, the primary handler resignals any exceptions 
caused by your program. 


9.4.3.2 Secondary Handler 
The secondary handler is used for special purposes and does not apply to 
the types of programs covered in this manual. 


9.4.3.3  Call-Frame Handlers (Application-Declared) 
Each routine of your program can establish a condition handler, also 
known as a call-frame handler. The operating system searches for these 
handlers starting with the routine that is currently executing. If no 
handler was established for that routine, the system searches for a handler 
established by the next routine down the call stack, and so on back to the 
main program, if necessary. 


After it is invoked, a handler might perform one of the following actions: 


e It handles the exception, thus allowing the program to continue 
execution. 


e It resignals the exception. The operating system then searches for 
another handler down the call stack. 


e It encounters a breakpoint or watchpoint, thereby suspending 
execution at the breakpoint or watchpoint. 


e It generates its own exception. In this case, the primary handler is 
invoked again. 


e It exits, thus terminating program execution. 
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9.4.3.4 Final and Last-Chance Handlers 
These handlers are controlled by the debugger. They enable the 
debugger to ultimately regain control and display the DBG> prompt if 
no application-declared handler has handled an exception. Otherwise, the 
debugging session would terminate, and control would pass to the DCL 
command interpreter. 


The final handler is the last frame on the call stack and the first of 
these two handlers to be invoked. The following example illustrates what 
happens when an unhandled exception is propagated from an exception 
breakpoint to the final handler: 


DBG> SET BREAK/EXCEPTION 
DBG> GO 


SSYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
break on exception preceding TEST\%LINE 13 

6: X := 3/Y; 
DBG> GO 
SSYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
DBG> 


In this example, the first INTDIV message is issued by the primary 
handler, and the second is issued by the final handler, which then displays 
the DBG> prompt. 


The last-chance handler is invoked only if the final handler cannot gain 
control because the call stack is corrupted. For example: 


DBG> DEPOSIT %FP = 10 
DBG> GO 


SSYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=0000000A, PC=0000319C, PSL=03C00000 
$DEBUG-E-LASTCHANCE, stack exception handlers lost, re-initializing stack 
DBG> 


The catchall handler, which is part of the VMS operating system, is 
invoked if the last-chance handler cannot gain control. The catchall 
handler produces a register dump. This should never occur if the debugger 
has control of your program. But it can occur if your program encounters 
an error when running without the debugger. 


If, during a debugging session, you observe a register dump and are 
returned to DCL level, submit an SPR to Digital. 


Exception-Related Built-in Symbols 


When an exception is signaled, the debugger sets the following exception- 
related built-in symbols. 
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Symbol Description 


%EXC_FACILITY Name of facility that issued the current exception 


%EXC_NAME Name of current exception 
%ADAEXC_NAME Ada exception name of current exception (for Ada programs 
only) 


%EXC_NUMBER Number of current exception 
%EXC_SEVERITY Severity code of current exception 


You can use these symbols as follows: 


e To obtain information about the fields of the VMS condition code of the 
current exception. 


e To qualify exception breakpoints (or tracepoints) so that they trigger 
only on certain kinds of exceptions. 


The following examples illustrate the use of some of these symbols. Note 
that the conditional expressions in the WHEN clauses are language- 
specific: 


DBG> EVALUATE SEXC_NAME 

‘ACCVIO’ 

DBG> SET TRACE/EXCEPTION WHEN (SEXC_NAME = "ACCVIO") 

DBG> EVALUATE SEXC_ FACILITY 

‘SYSTEM’ 

DBG> EVALUATE SEXC_NUMBER 

12 

DBG> EVALUATE/CONDITION_VALUE %SEXC_ NUMBER 

SSYSTEM-F-ACCVIO, access violation, reason mask=01, virtual address=FFFFFF30, PC=00007552, PSL=03C00000 
DBG> SET BREAK/EXCEPTION WHEN (SEXC_NUMBER = 12) 

DBG> SET BREAK/EXCEPTION WHEN (SEXC_SEVERITY .NE. "I" .AND. SEXC SEVERITY SNE. “S") 





Debugging Exit Handlers 


Exit handlers are procedures that are called whenever an image requests 
the $EXIT system service or runs to completion. A user program can 
declare one or more exit handlers. The debugger always declares its own 
exit handler. 


At program termination, the debugger exit handler executes after all 
application-declared exit handlers have executed. 


To debug an application-declared exit handler, proceed as follows: 
1 Seta breakpoint in that exit handler. 


2 Cause the exit handler to execute, by means of one of the following 
techniques: 


e Include in your program an instruction that invokes the exit 
handler (usually a call to $EXIT). 


° Allow your program to terminate. 


e Enter the EXIT command. (Note that the QUIT command does not 
execute any user declared exit handlers.) 


When the exit handler executes, the breakpoint is activated and 
control is then returned to the debugger, which prompts for commands. 
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The SHOW EXIT_HANDLERS command gives a display of the exit 
handlers that your program has declared. The exit handler routines 
are displayed in the order that they are called. A routine name is 
displayed symbolically, if possible. Otherwise its address is displayed. 
The debugger’s exit handlers are not displayed. For example: 


DBG> SHOW EXIT HANDLERS 

exit handler at STACKS\CLEANUP 

exit handler at BLIHANDLER\HANDLERL1 
DBG> 


9.6 Debugging AST-Driven Programs 


A program can use asynchronous system traps (ASTs) either explicitly, 

or implicitly by calling VMS system services or RTL routines that call 
application-defined AST routines. Section 9.6.1 explains how to facilitate 
debugging by disabling and enabling the delivery of ASTs originating with 
your program. Section 9.6.2 explains how delivery of an AST affects a 
SHOW CALLS display. 


9.6.1. Disabling and Enabling the Delivery of ASTs 


Debugging AST-driven programs can be confusing because interrupts 
originating from the program being debugged can occur, but are not 
processed, .while the debugger is running (processing commands, tracing 
execution, displaying information, and so on). 


By default, the delivery of ASTs is enabled while the program is running. 
The command DISABLE AST disables the delivery of ASTs while the 
program is running and causes any such potential interrupts to be queued. 


The delivery of ASTs is always disabled when the debugger is running. 


The command ENABLE AST reenables the delivery of ASTs, including any 
pending ASTs. The command SHOW AST indicates whether the delivery 
of ASTs is enabled or disabled. 


To control the delivery of ASTs during the execution of a routine called 
with the CALL command, use the /[NOJAST qualifiers. The command 
CALL/AST enables the delivery of ASTs in the called routine. The 
command CALL/NOAST disables the delivery of ASTs in the called 
routine. If you do not specify /AST or /NOAST with the CALL command, 
the delivery of ASTs is enabled unless you have previously entered the 
command DISABLE AST. 


9.6.2 Cail Frames Associated with ASTs in SHOW CALLS Display 
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Assume that a program calls the system service $SETIMR to set a timer 
that expires at a specified interval and then execute an application-defined 
AST routine, TIMER ROUT, in the program. 


The following command lines set a breakpoint on routine TIMER_ROUT, 
start execution which is then suspended on that routine, and display the 
sequence of active calls at the breakpoint: 


DBG> SET BREAK TIMER ROUT 


DBG> GO 
break at routine MOD1\TIMER_ ROUT 
14: XS eo Roe ES 

DBG> SHOW CALLS 

module name routine name line rel PC abs PC 

*MOD1 TIMER ROUT 14 00000002 OQO000040E 
00000000 80009E5E 

DBG> 


The bottom line is the call frame associated with the system AST 
dispatcher. It shows the absolute PC value when the AST was delivered. 
Because the AST dispatcher is in system space (as indicated by the high 
absolute address), no symbolic information (module name, routine name, 
line number) is available. A SHOW CALLS display associated with the 
delivery of an AST might also show some debugger call frames (module 
name SHARE$DEBUG) and diagnostic messages related to condition 
handling by the debugger. You should ignore such messages and call 
frames. 
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This chapter explains how to use features of the debugger that are specific 
to multiprocess programs—that is, programs that run in more than one 
process. The features enable you to display process information and 
control the execution of specific processes. When debugging a multiprocess 
program, use these features in addition to those explained in other 
chapters. 


The first section gets you started with multiprocess debugging. The 
remaining sections provide additional information. 


Throughout the chapter it is assumed that all images discussed are 
"debuggable" images—that is, images that can be brought under control 
of the debugger. A debuggable image is one that was not linked with the 
/NOTRACEBACK command qualifier. As explained in Chapter 5, you have 
full symbolic information when debugging an image only if its modules 
were compiled and linked with the /DEBUG command qualifier. 





10.1 Getting Started 


This section gives an overview of the multiprocess debugging environment 
and explains the basic techniques used to debug a multiprocess program. 
Refer to subsequent sections for additional details. 


10.1.1. Establishing a Multiprocess Debugging Configuration 


Before invoking the debugger, enter the following command to establish a 
multiprocess configuration: 


$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 


This command establishes a multiprocess configuration for the VMS 

job hierarchy in which the command was entered. As a result, after a 
debugging session is started, any debuggable image running in the same 
job can be controlled from that one session. 


See Section 10.2.1 for more information about debugging configurations 
and process relationships. See Section 10.2.9 for system requirements 
related to multiprocess debugging. 


10.1.2 Invoking the Debugger 


This section explains the usual way of starting a multiprocess debugging 
session. See Section 10.2.4 for additional techniques for invoking the 
debugger (for example, using the CTRL/Y_DEBUG sequence or the 
CONNECT command). | 
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$ RUN MAIN PROG 
VAX DEBUG Version 5.4 


You typically initiate the execution of a multiprocess program by running 
the main image in the main (master) process. After the main image 

is running in the main process, the program might spawn one or more 
subprocesses to run additional images by issuing a LIB$SPAWN run-time 
library call or a $CREPRC system service call. 


If the main image is debuggable, the debugger is invoked when you run 
the image. For example: 


SDEBUG-I-INITIAL, language is FORTRAN, module set to MAIN PROG 
*DEBUG-I-NOTATMAIN, type GO to get to start of main program 
predefined trace on activation at routine MAIN PROG in %PROCESS NUMBER 1 


DBG 1> 


As with a one-process program, the debugger displays its banner and 
prompt just prior to the start of execution of the main image. However, 
note two differences: the "predefined trace on ... " message and the 
debugger prompt. 


In a multiprocess configuration, the debugger traces each new process 
that is brought under control. In this case, the debugger traces the 
first process, which runs the main image of the program. (%7PROCESS_ 
NUMBER is a built-in symbol that identifies a process number, just as 
%LINE identifies a line number.) 


The significance of the prompt suffix ('_1’) is explained in the next 
section. 


10.1.3 Visible Process and Process-Specific Commands 
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The previous example shows that the debugger prompt in a multiprocess 
debugging configuration is different from that found in the default 
configuration. 


In a multiprocess configuration, "dynamic prompt setting" is enabled by 
default (SET PROMPT/SUFFIX=PROCESS_NUMBER). Therefore, the 
prompt has a process-specific suffix that indicates the process number of 
the visible process. The debugger assigns a process number sequentially, 
starting with process 1, to each process that comes under the control of a 
given debugging session. 


The visible process is the process that is the default context for issuing 
process-specific commands. Process-specific commands are those that 
start execution (STEP, GO, and so on) and those used for looking up 
symbols, setting breakpoints, looking at the call stack and registers, and 
so on. Commands that are not process specific are those that do not 
depend on the mapping of memory but, rather, affect the entire debugging 
environment (for example, keypad mode and screen mode commands). 


Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX), 
the debugger prompt suffix always identifies the visible process (for 
example, DBG_1>). The SET PROMPT command provides several options 
for tailoring the prompt-string prefix and suffix to your needs. 
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10.1.4 Obtaining Information about Processes 


Use the SHOW PROCESS command to obtain information about processes 
that are currently under control of your debugging session. By default, 
SHOW PROCESS displays one line of information about the visible 
process. The following example shows the kind of information displayed 
immediately after you invoke the debugger: 


DBG 1> SHOW PROCESS 


Number Name Hold State Current PC 
* 1 JONES activated MAIN PROG\SLINE 2 
DBG _1> 


A one-line SHOW PROCESS display provides the following information 
about each process specified: 


e The process number assigned by the debugger. In this case, the 
process number is 1 because this is the first process known to the 
debugger. The asterisk in the leftmost column (*) marks the visible 
process. 


¢ The VMS process name. In this case, the VMS process name is 
JONES. 


¢ Whether the process has been put on hold with a SET PROCESS 
/HOLD command, as explained in Section 10.1.7.2. (This process has 
not been put on hold.) 


e The current debugging state for that process. A process is in the 
"activated" state when it is first brought under debugger control (that 
is, before it has executed any part of the program under debugger 
control). Table 10-1 summarizes the possible debugging states that 
can appear in the state column. 


¢ The location (symbolized, if possible) where execution of the image 
is suspended in that process. In this case, the image has not started 
execution. 


Table 10-1 Debugging States 


Activated The image and its process have just been brought under 
debugger control, either through a DCL RUN/DEBUG 
command, a debugger CONNECT command, a | 
CTRL/Y—DEBUG sequence, or by the program signaling 
SS$_DEBUG while it was not under debugger control. 

Break’ A breakpoint was triggered. 


Interrupted Execution was interrupted in that process, either because 
execution was suspended in another process, or because 
the user interrupted execution with the abort-key sequence 
(CTRL/C, by default). 


Step’ A STEP command has completed. 


'See the SHOW PROCESS command in the command dictionary for a list of additional states. 


(continued on next page) 
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Table 10—1 (Cont.) Debugging States 


Terminated The image has terminated execution but the process is 
still under debugger control. Therefore, you can obtain 
information about the image and its process. 


Trace" A tracepoint was triggered. 
Unhandled exception An unhandled exception was encountered. 
Watch of A waichpoint was triggered. 


'See the SHOW PROCESS command in the command dictionary for a list of additional states. 


The SHOW PROCESS/ALL command provides information about all 
processes that are currently under debugger control (in the case of the 
previous example, a SHOW PROCESS/ALL command would show only 
process 1). The SHOW PROCESS/FULL command provides additional 
details about processes. 


Returning to the previous example, if you now enter a STEP command 
followed by a SHOW PROCESS command, the state column in the SHOW 
PROCESS display indicates that execution is suspended at the completion 
of a step: 


DBG_1> SHOW PROCESS 


Number Name Hold State Current PC 
. 1 JONES step MAIN PROG\%SLINE 3 
DBG 1> 


Similarly, if you were to set a breakpoint and enter a GO command, a 
SHOW PROCESS command entered at the prompt after the break point 
has triggered would identify the state as "break". 


10.1.5 Bringing a Spawned Process Under Debugger Control 
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Continuing with the example from the last section, assume that you have 
entered a few more STEP commands and, in the middle of a step, MAIN_ 
PROG spawns a process to run a debuggable image called TEST. 


Because DBG$PROCESS has the value MULTIPROCESS, the spawned 
process is now requesting to connect to the current debugging session, and 
the image TEST is suspended at the start of execution. 


While the spawned process is waiting to be connected, it is not yet known 
to the debugger and cannot be identified in a SHOW PROCESS/ALL 
display. You can bring the process under debugger control using either of 
the following methods: 


e Enter a command, such as STEP, that starts execution. 


e Enter the CONNECT command without specifying a parameter. The 
CONNECT command is preferable in cases when you do not want the 
program to execute further. 
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The following example illustrates use of the CONNECT command: 


DBG 1> STEP 
stepped to MAIN PROG\SLINE 18 in SPROCESS NUMBER 1 _ 

18: LIBSSPAWN ("RUN/DEBUG TEST") 

DBG 1> STEP 

stepped to MAIN PROG\SLINE 21 in %SPROCESS NUMBER 1 

21% X= 7 

DBG 1> CONNECT 

predefined trace on activation at routine TEST in ®PROCESS NUMBER 2 
DBG 1> 


In this example, the second STEP command takes you past the 
LIB$SPAWN call that spawns the process. The CONNECT command 
brings the waiting process under debugger control. After entering the 
CONNECT command, you might need to wait a moment for the process 
to connect. The "predefined trace on ... " message, as explained in 
Section 10.1.2, indicates that the debugger has taken control of a new 
process and identifies that process as process 2, the second process known 
to the debugger in this session. 


A SHOW PROCESS/ALL command, entered at this point, identifies the 
debugging state for each process and the location at which execution is 


suspended: 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

* 1 JONES step MAIN PROG\%SLINE 21 
2 JONES 1 activated TEST\SLINE 1+2 

DBG_1> 


Note that the CONNECT command brings any processes that are waiting 
to be connected to the debugger under debugger control. If no processes 
are waiting, you can press CTRL/C to abort the CONNECT command and 
display the debugger prompt. 


Broadcasting Commands to Specified Processes 


By default, process-specific commands are executed in the context of the 
visible process. The DO command enables you to execute commands in 
the context of one or more processes that are currently under debugger 
control. This is also referred to as "broadcasting" commands to processes. 


Use the DO command without a qualifier to execute commands in the 
context of all of the processes. For example, the following command 
executes the SHOW CALLS command for all processes currently under 
debugger control (processes 1 and 2, in this case): 


DBG_1> DO (SHOW CALLS) 
For %PROCESS NUMBER 1 


module name routine name line rel PC abs PC 

*MAIN PROG MAIN PROG 21 OOOOO0O01E 0O000041F 
For tPROCESS NUMBER 2 , 

module name routine name line rel PC abs PC 

TEST TEST 1+2 OO0OO00000B 0000040B 


_As indicated in this example, the debugger identifies the process associated 
with any debugger output. 
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Use the DO command with the /PROCESS= qualifier to execute commands 
in the context of specific processes. For example, the following command 
executes the commands SET MODULE START and EXAMINE X in the 
context of process 2: 


DBG 1> DO/PROCESS=(%SPROC 2) (SET MODULE START; EXAMINE X) 


For more information about how to specify processes in debugger 
commands, see Section 10.2.2. 


10.1.7 Controlling Execution 
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Program execution in a multiprocess debugging environment follows these 
conventions: 


e When you enter a command that starts program execution, such as 
STEP or GO, the command is executed in the context of the visible 
process. However, images in any other processes that have not been 
put on hold (with a SET PROCESS/HOLD command) are also allowed 
to execute. Similarly, if you use the DO command to broadcast a 
command to start execution in one or more processes, the command is 
executed in the context of each specified process that is not on hold, 
but images in any other processes that are not hold are also allowed to 
execute. In all cases, a hold condition is ignored in the visible process. 
(See Section 10.1.7.2 for additional information about the behavior of 
processes on hold.) 


e After execution is started, the way in which it continues depends on 
whether the command SET MODE [NOJINTERRUPT was entered. 
By default (SET MODE INTERRUPT), execution continues until it 
is suspended in any process. At that point, execution is interrupted 
in any other processes that were executing images, and the debugger 
prompts for input. 


These concepts are illustrated next by continuing with the example in 
Section 10.1.5 that illustrates the use of the CONNECT command. 


In that example, the "stepped to..." messages indicate that both commands 
are executed in the context of process 1, the visible process. The second 
STEP command spawns process 2. The SHOW PROCESS/ALL example of 
Section 10.1.5 indicates that execution in processes 1 and 2 is suspended 
at MAIN_PROG\ %LINE 21 and TEST\ @LINE 1+2, respectively. 


At this point, entering another STEP command followed by SHOW 
PROCESS/ALL results in the following display: 


DBG 1> STEP 3 
stepped to MAIN PROG\SLINE 23 in %PROCESS NUMBER 1 
Zo Y = 15 

DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 

* 1 JONES step MAIN PROG\SLINE 23 
2 JONES 1 interrupted TEST\SLINE 3+1 

DBG_1> | 
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The STEP command is executed in the context of process 1, the visible 
process. After the STEP command, execution in process 1 is suspended 
at MAIN_PROG\ %@%LINE 23. However, the STEP command also causes 
execution to start in process 2. The completion of the STEP command in 
process 1 causes execution in process 2 to be interrupted at TEST\ 2LINE 
3+1. 


Section 10.1.7.1 describes another mode of execution, which is provided by 
the command SET MODE NOINTERRUPT. 


10.1.7.1 Controlling Execution with SET MODE NOINTERRUPT 
The command SET MODE NOINTERRUPT allows execution to continue 
without interruption in other processes when it is suspended in some 
process. This is especially useful if, for example, you want to broadcast a 
STEP command to several processes with the DO command, then complete 
execution of the STEP command in all these processes. For example: 


DBG_1> SET MODE NOINTERRUPT 
DBG_1> DO (STEP) 


In this example, the DO command executes the STEP command in the 
context of all processes. The visible process and any other processes 

that are not on hold start execution. Because the command SET MODE 
NOINTERRUPT was entered, the prompt is displayed only after the 
STEP command has completed execution (or execution has been otherwise 
suspended at a breakpoint or watchpoint) in all processes that were 
executing. | 


When SET MODE NOINTERRUPT is in effect, as long as execution 
continues in any process, the debugger does not prompt for input. In such 
cases, use CTRL/C to interrupt all processes and display the prompt. 


10.1.7.2 Putting Specified Processes on Hold 
As indicated in the preceding sections, a command that starts execution is 
executed in the context of the visible process, but it also causes execution 
to start in other processes. If you want to inhibit execution in a process, 
put it on hold. For example, the following SET PROCESS/HOLD command 
puts process 2 on hold. The subsequent STEP command is executed in the 
context of process 1, the visible process. Execution also starts in any other 
processes that are not on hold, but not in process 2: 


DBG 1> SET PROCESS/HOLD %PROC 2 
DBG_1> STEP 


A SHOW PROCESS a a indicates whether a process is on hold. For 


example: 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current: PC 

x 1 JONES step MAIN PROG\SLINE 24 
2 JONES 1 HOLD interrupted TEST\SLINE 3+1 

DBG 1> 


To release a process from the hold condition, enter the command eh 
PROCESS/NOHOLD, and specify the process. 
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Note that a hold condition is ignored in the visible process. Therefore, 
the command SET PROCESS/HOLD/ALL is a convenient way to confine 
execution to the visible process. In the following example, execution starts 
only in the visible process: 


DBG_ 1> SET PROCESS/HOLD/ALL 
DBG_1> STEP 


This feature is useful if, for example, you want to use the CALL command 
to execute a dump routine that is not part of the execution stream of your 
program. 


The preceding discussions also apply if you use the DO command to 
broadcast a GO, STEP, or CALL command to several processes. The GO, 
STEP or CALL command is executed in the context of each specified 
process that is not on hold, and execution also starts in any other process 
that is not on hold. The following example illustrates the execution 
behavior when all processes are put on hold and commands are broadcast 
to all processes. Execution starts only in the visible process (process 1, in 
this example): 


DBG_1> SET PROCESS/HOLD/ALL 
DBG 1> DO (EXAMINE X; STEP) 
For tPROCESS NUMBER 1 


MAIN PROG\X: 78 
For %PROCESS NUMBER 2 
TEST\X: 29 


stepped to MAIN PROG\SLINE 26 in %SPROCESS NUMBER 1 
26: K=K+1 
DBG 1> 


10.1.8 Changing the Visible Process 


Use the SET PROCESS command (with the default /VISIBLE qualifier) to 
establish another process as the visible process. For example, the following 
command makes process 2 the visible process: 


DBG _1> SET PROCESS %PROC 2 
DBG 2> 


In this example, because dynamic prompt setting is enabled by default, 
the SET PROCESS command also has caused the prompt string suffix 
to change. It now indicates that process 2 is the visible process. All 
process-specific commands are now executed in the context of process 2. 
For example, a SHOW CALLS command would display the call stack for 
the image running in process 2. 


10.1.9 Dynamic Process Setting 
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By default, "dynamic process setting" is enabled (SET PROCESS 
/DYNAMIC). As a result, whenever the debugger suspends program 
execution and displays its prompt, the process in which execution is 
suspended becomes the visible process automatically. Dynamic process 
setting occurs in the following situations: when a breakpoint or watchpoint 
is triggered, at an exception condition, on the completion of a STEP 
command, or when the last process performs an image exit. 


Debugging Multiprocess Programs 
10.1 Getting Started 


When dynamic process setting is disabled ((NODYNAMIC), the visible 
process remains unchanged until you specify another process with the SET 
PROCESS/VISIBLE command. 


Dynamic process setting is illustrated in the following example, which also 
illustrates dynamic prompt setting: 


DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 

* 1 JONES step MAIN PROG\SLINE 22 
2 JONES 1 interrupted TEST\SLINE 4 

DBG_ 1> DO/PROCESS=(%PROC 2) (SET BREAK SLINE 11) 


DBG 1> GO 


break at TEST\%LINE 11 in %PROCESS NUMBER 2 
DBG 2> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
1 JONES interrupted MAIN PROG\%LINE 28 
= 2 JONES 1 break TEST\SLINE 11 
DBG 2> 


In this example, process 1 is initially the visible process, as indicated by 
the prompt and the SHOW PROCESS display. The DO command sets 
a breakpoint in the context of process 2. Execution is resumed with the 
GO command and is suspended at the breakpoint in process 2. Process 
2 is now the visible process, as indicated by the prompt and the SHOW 
PROCESS display. 


If you have entered the command SET MODE NOINTERRUPT and then 
started execution in several processes with the DO command, the prompt 
is displayed only after execution has been suspended in all processes. In 
this case, the visible process remains unchanged, unless the last process 

performs an image exit (and thereby becomes the visible process). 


10.1.10 Monitoring the Termination of Images 


When the main image of a process runs to completion, the process goes 
into the "terminated" debugging state (not to be confused with process 
termination in the VMS sense). This condition is traced by default, as if 
you had entered the command SET TRACE/TERMINATING. 


When a process is in the terminated debugging state, it is still known to 
the debugger and appears in a SHOW PROCESS/ALL display. You can 
enter commands to examine variables, and so on. 


When the last image of the program exits, the debugger gains control and 
displays its prompt. 


10.1.11 Ending the Debugging Session 


To end the entire debugging session, use the EXIT or QUIT command 
without specifying any parameters. 


EXIT executes any exit handlers that are declared in the program. QUIT 
does not. 
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Thus, when you do not specify any parameters, the behavior of EXIT 
and QUIT is analogous to their behavior for the default debugging 
configuration. 


10.1.12 Terminating Specified Processes 


To terminate specified processes without ending the debugging session, use 
the EXIT or QUIT command, specifying one or more process specifications 
as parameters. For example, the following command terminates the image 
running in process 2 and terminates the process: 


DBG_3> EXIT %PROC 2 
DBG 3> 


Subsequently, process 2 does not appear in a SHOW PROCESS display. 
See the command dictionary for complete details on the EXIT and QUIT 
commands. 


10.1.13 Interrupting Program Execution 


Pressing CTRL/C (or the abort-key sequence established with the SET 
ABORT_KEY command) interrupts execution in every process that is 


currently running an image. This is indicated as an "interrupted" state in 
a SHOW PROCESS display. 


As in the default configuration, you can also use CTRL/C to abort a 
debugger command. 





10.2 Supplemental Information 


This section provides additional details or more advanced concepts and 
usages than those covered in Section 10.1. 


10.2.1 Debugging Configurations and Process Relationships 
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You can invoke the debugger in either the default or the multiprocess 
configuration to debug programs that run in either one or several 
processes, respectively. 


The debugging configuration depends on the current definition of the 
logical name DBG$PROCESS, as indicated in the following table. 


Definition of Logical Name 


DBG$PROCESS Resulting Debugging Configuration 

Undefined or DEFAULT Default (use this configuration with a program that 
| runs in one process) 

MULTIPROCESS Multiprocess (use this configuration with a program 


that runs in several processes) 


Note that the debugging configuration does not depend on whether 
the program runs in one or several processes. Rather, the value of 
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DBG$PROCESS determines whether debuggable images running in 
different processes can be controlled from the same debugging session. 


Before invoking the debugger, enter the DCL command SHOW LOGICAL 
DBG$PROCESS to determine the current definition of DBG$PROCESS 
and the resulting debugging configuration. 


10.2.1.1 Establishing a Default Debugging Configuration 
Use the command SHOW LOGICAL DBG$PROCESS to determine the 
current debugging configuration. 


In the following example, the output of the command indicates that a 
default debugging configuration is in effect: 


S$ SHOW LOGICAL DBGSPROCESS 
%SHOW~S-NOTRAN, no translation for logical name DBGSPROCESS 


If DBG$PROCESS has the value MULTIPROCESS, and you want to 
debug a program that runs in only one process, enter the following 
command: 


$ DEFINE DBGSPROCESS DEFAULT 


10.2.1.2 Establishing a Multiprocess Debugging Configuration 
The multiprocess debugging configuration enables you to interact with 
several processes from one debugging session. 


Use the following command to establish a multiprocess debugging 
configuration: 


$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 


As shown in this example, when defining DBG$PROCESS for a 
multiprocess configuration, use a job logical definition so that the definition 
applies to all processes in that job. An image can be connected to (and 
controlled by) an existing multiprocess debugging session only if the 
process running the image is in the same job as the process running the 
debugging session. 


In the typical multiprocess scenario, the program runs in one master 
parent process and several subprocesses. The debugger is invoked 
from the master process, then the program creates subprocesses during 
execution (a subprocess can also become the parent of another level of 
subprocesses). 


Another possible scenario is that the program runs in several peer 
processes. There is no master process. This configuration would result 
if you invoked the debugger by running one debuggable image and then 
used the SPAWN/NOWAIT command repeatedly to spawn other processes 
and run a debuggable image in each spawned process. 
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10.2.1.3 Process Relationships When Debugging 


The debugger consists of two parts: A relatively small kernel 
debugger image (DEBUG.EXE) and a larger main debugger image 
(DEBUGSHR.EXE) that contains most of the debugger code. This 
separation reduces potential interference between the debugger and 
the program being debugged. 


The separation also makes it possible to have two debugging 
configurations: a default configuration and a multiprocess configuration. 
Regardless of the configuration, the presence of a main debugger running 
in some process establishes a unique debugging session. 


When you invoke the debugger in the default configuration, the program 

runs in its process along with the kernel debugger, and a new subprocess is 
created to run the main debugger. A new main debugger (and, therefore, a 
new debugging session) is established every time you invoke the debugger. 


In the multiprocess configuration, the program being debugged runs in 
several processes. Each process that is running one or more images under 
debugger control is also running a local copy of the kernel debugger. The 
main debugger, running in a separate subprocess, communicates with the 
other processes through their kernel debuggers. 


Although all processes of a multiprocess configuration must be in the 
same job, they do not have to be related in a particular process/subprocess 
hierarchy. Moreover, the program images running in separate processes do 
not have to communicate with each other. 


See Section 10.2.9 for system requirements related to multiprocess 
debugging. 


10.2.2 Specifying Processes in Debugger Commands 
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When specifying processes in debugger commands, you can use any of 
the forms listed in Table 10-2, except when specifying processes with the 
CONNECT command (see Section 10.2.4.2). 


The CONNECT command is used to bring a process that is not yet known 
to the debugger under debugger control. Therefore, when specifying a 
process with CONNECT, you can use only its VMS process name or VMS 
process identification number (PID). You cannot use its debugger-assigned 
process number or any of the process built-in symbols (for example, 
%NEXT_PROCESS) for the process. 
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Table 10-2 Process Specifications 


[%PROCESS_NAME] process-name 


[%PROCESS_NAME] "process-name" 


%PROCESS _PID process_id 


%PROCESS_NUMBER process-number (or 
%PROC process-number) 


process-group-name 
%NEXT_ PROCESS 
%PREVIOUS PROCESS 


%VISIBLE_PROCESS 


The VMS process name, if that name 
contains no spaces or lowercase 
characters’. 


The VMS process name, if that 
name contains spaces or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


The VMS process identification number 
(PID, a hexadecimal number). 


The number assigned to a process 
when it comes under debugger 
control. A new number is assigned 
sequentially, starting with 1, to each 
process. If a process is terminated 
with the EXIT or QUIT command, 

the number is not reused during the 
debugging session. Process numbers 
appear in a SHOW PROCESS display. 
Processes are ordered in a circular list 
so they can be indexed with the built-in 
symbols %PREVIOUS_PROCESS and 
%NEXT_PROCESS. 


A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 


The next process after the visible 
process in the debugger’s circular 
process list. 


The process previous to the visible 
process in the debugger’s circular 
process list. 


The process whose stack, register set, 
and images are the current context for 
looking up symbols, register values, 
routine calls, breakpoints, and so on. 


'The process name can include the wildcard character (*) 





You can omit the %PROCESS_NAME built-in symbol when entering 


commands. For example: 


DBG_2> SHOW PROCESS %PROC 2, JONES 3 


You can define a symbol to represent a group of processes (DEFINE 
/PROCESS_GROUP). This enables you to enter commands in abbreviated 


form. For example: 
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DBG_1> DEFINE/PROCESS GROUP SERVERS=FILE SERVER, NETWORK_SERVER 
DBG_1> SHOW PROCESS SERVERS 


Number Name Hold State Current PC 

* 1 FILE SERVER step FS PROG\%SLINE 37 
2 NETWORK_SERVER break NET_PROG\%LINE 24 

DBG_1> 


The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and 
%PREVIOUS_PROCESS are useful in control structures based on the IF, 
WHILE, or REPEAT commands and in command procedures. 


10.2.3. Monitoring Process Activation and Termination 


By default, a tracepoint is triggered when a process comes under debugger 
control and when it performs an image exit. These predefined tracepoints 
are equivalent to those resulting from entering the commands SET TRACE 
/ACTIVATING and SET TRACE/TERMINATING, respectively. You can set 
breakpoints on these events by means of the SET BREAK/ACTIVATING 
and SET BREAK/TERMINATING commands. 


To cancel the predefined tracepoints, use the CANCEL TRACE 
/PREDEFINED command with the /ACTIVATING and /TERMINATING 
qualifiers. To cancel any user-defined activation and termination 
breakpoints, use the CANCEL BREAK command with the /ACTIVATING 
and /TERMINATING qualifiers (the /USER qualifier is assumed by default 
when canceling breakpoints or tracepoints). 


The debugger prompt is displayed when the first process comes under 
debugger control. This enables you to enter commands before the main 
image has started execution, as with a one-process program. 


Also, the debugger prompt is displayed when the last process performs an 
image exit. This enables you to enter commands after the program has 
completed execution, as with a one-process program. 


10.2.4 Interrupting the Execution of an Image to Connect it to the Debugger 


You can interrupt a debuggable image that is running without debugger 
control in a process and connect that process to the debugger. 


e To start a new debugging session, use the CTRL/Y—DEBUG sequence 
from DCL level. 


¢ To interrupt an image and connect it to an existing debugging session, 
use the CONNECT command. 


10.2.4.1 Using the CTRL/Y—DEBUG Sequence to Invoke the Debugger , 
You use the CTRL/Y—DEBUG sequence with the multiprocess debugging 
configuration exactly as with the default configuration. That is, run 
the image from DCL level with the RUN/NODEBUG command, then 
press CTRL/Y to interrupt the image. The DEBUG command causes the 
debugger to be invoked. (See Section 3.1.2.) 
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The following example shows how you might start a new debugging 


session: 


S DEFINE/JOB DBGSPROCESS MULTIPROCESS 


S$ RUN/NODEBUG PROG2 


Interrupt 
$ DEBUG 


VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in SPROCESS NUMBER 1 


DBG_1> 


In this example, the DEFINE/JOB command establishes a multiprocess 
debugging configuration. The RUN/NODEBUG command starts the 
execution of image PROG2 without debugger control. The CTRL/Y— 
DEBUG sequence interrupts execution and invokes the debugger. 


The VAX DEBUG banner indicates that a new debugging session has been 
started. The process-specific prompt (DBG_1>) indicates that this is a 
multiprocess configuration and that execution is suspended in process 1, 
which is running image PROG2. 


The activation tracepoint identifies the location at which execution was 
interrupted (and at which the debugger took control of the process). You 
can also use the SHOW CALLS command to display the call stack at that 
location. 


After the debugger has been invoked, you can use the CONNECT 
command to bring other processes under debugger control. In the previous 
example, you could use the CONNECT command to bring processes under 
debugger control that were created by PROG2 before you interrupted its 
execution (see Section 10.2.4.2). 


When using the CTRL/Y—DEBUG sequence, if a multiprocess debugging 
session already exists in the same job as the image that is interrupted, 
the image connects to that session. In this case, because a new session is 
not started, the VAX DEBUG banner is not displayed when the debugger 
takes control. This situation could occur if, for example, you entered 

a SPAWN/NOWAIT command from the session, started execution with 

a RUN/NODEBUG command, and then entered a CTRL/Y—DEBUG 
sequence. 


10.2.4.2 Using the CONNECT Command to Interrupt an Image 


The CONNECT command, used without a parameter, was introduced in 
Section 10.1.5. When used with a parameter, the CONNECT command 
enables you to interrupt a debuggable image that is running without 
debugger control and bring it under control of your current debugging 
session. 


The image might have been activated as follows: 


e Your program issued a LIB$SPAWN run-time library call or a 
$CREPRC system service call to spawn a process and run an image 
without debugger control 
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e You started execution with a RUN/NODEBUG command entered at 
DCL level 


In the following example, the CONNECT command causes the image 
running in process JONES_3 to be interrupted and to come under control 
of the current debugging session. Process JONES_3 must be in the same 
job as the session. 


DBG 1> CONNECT JONES 3 


Note that a process is not identified by a debugger process number until it 
is connected to a debugging session. Therefore, when specifying a process 
with the CONNECT command, you can use only its VMS process name or 
VMS process identification number (PID). 


The effect of the CONNECT command is equivalent to attaching to 
a process from a debugging session and then entering the sequence 
CTRL/Y—DEBUG to interrupt the running image and invoke the 
debugger. However, the CONNECT command is easier to enter and 
also enables you to interrupt a process to which you cannot attach. 


10.2.5 Screen Mode Features for Multiprocess Debugging 


Screen mode displays, whether predefined or user defined, are associated 
with the visible process by default. For example, SRC shows the source 
code where execution is suspended in the visible process, OUT shows the 
output of commands executed in the context of the visible process, and so 
on. 


By using the /PROCESS qualifier with the DISPLAY command you can 
create process-specific displays or make existing displays process specific, 
respectively. The contents of a process-specific display are generated and 
modified in the context of that process. You can make any display process 
specific except for the PROMPT display. For example, the following 
command creates the automatically updated source display SRC_38, which 
shows the source code where execution is suspended in process 3: 


DBG_2> DISPLAY/PROCESS=(%PROC 3) SRC_3 AT RS23 SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC) 
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You assign attributes to process-specific displays as for displays that are 
not process specific. For example, the following command makes display 
SRC_3 the current scrolling and source display—that is, the output of 
SCROLL, TYPE, and EXAMINE/SOURCE commands are then directed at 
SRC_3: 


DBG_2> SELECT/SCROLL/SOURCE SRC 3 


If you enter a DISPLAY/PROCESS command without specifying a process, 
the specified display is then specific to the process that was the visible 
process when you entered the command. For example, the following 
command makes OUT_X specific to process 2: 


DBG_2> DISPLAY/PROCESS OUT X 
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The /SUFFIX qualifier appends a process identifying suffix that denotes 
the visible process to a display name. This qualifier can be used directly 
after a display name in any command that specifies a display (for example, 
DISPLAY, EXTRACT, SAVE). It is especially useful within command 
procedures in conjunction with display definitions or key definitions that 
are bound to display definitions. 


In a multiprocess configuration, the predefined tracepoint on process 
activation automatically creates a new source display and a new 
instruction display for each new process that comes under debugger 
control. The displays have the names SRC_n and INST_n, respectively, 
where n is the process number. These displays are initially marked as 
removed. They are automatically deleted on process termination. 


Several predefined keypad key sequences enable you to configure your 
screen with the process-specific source and instruction displays that are 
created automatically when a process is activated. Key sequences that are 
specific to multiprocess programs are as follows: PF1—-9, PF4-9, PF4—7, 
PF4—3, PF4—1. See Section B.5 for the general effect of these sequences. 
Use the SHOW KEY command to determine the exact commands. 


10.2.6 Setting Watchpoints in Global Sections 


You can set watchpoints in global sections. A global section is a region of 
memory that is shared among all processes of a multiprocess program. A 
watchpoint that is set on a location in a global section (a global section 
watchpoint) triggers when any process modifies the contents of that 
location. 


When setting watchpoints on arrays or records, note that performance 
is improved if you specify individual elements rather than the entire 
structure with the SET WATCH command. 


If you set a watchpoint on a location that is not yet mapped to a global 
section, the watchpoint is treated as a conventional static watchpoint. For 
example: | 


DBG_1> SET WATCH ARR(1) 
DBG 1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 


When ARR is subsequently mapped to a global section, the watchpoint is 
automatically treated as a global section watchpoint and an informational 
message is issued. For example: 


DBG 1> GO 
SDEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has been remapped 
to a global section 
predefined trace on activation at routine PPL3 in %PROCESS NUMBER 2 
predefined trace on activation at routine PPL3 in *PROCESS NUMBER 3 
watch of PPL3\ARR(1) at PPL3\%LINE 93 in *PROCESS NUMBER 2 
933 ARR(1) = INDEX 

old value: 0 

new value: 1 
break at PPL3\%LINE 94 in SPROCESS NUMBER 2 

94: ARR(I) = I 
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After the watched location is mapped to a global section, the watchpoint is 
visible from each process. For example: 


DBG _2> DO (SHOW WATCH) 
For SPROCESS NUMBER al 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For SPROCESS NUMBER 2 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For SPROCESS NUMBER 3 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 


10.2.7 Using Multiprocess Commands with the Default Configuration 


10.2.8 


All commands, qualifiers, and built-in symbols that are provided for 

multiprocess debugging are also understood in the default debugging 
configuration and have analogous behaviors (where applicable). For 

example: 


¢ The EXIT command without a parameter ends a debugging session in 
both configurations. 


¢ A DO command without the /PROCESS qualifier executes the 
commands specified in all processes. 


¢ In the default configuration, the visible process is the process that runs 
the entire program. It is identified as process 1 in a SHOW PROCESS 
display. 


e Process-specific built-in symbols, such as %PROCESS_NUMBER 
and %VISIBLE_PROCESS, are interpreted correctly in the default 
configuration. 


This compatibility enables you to use command procedures designed for 
multiprocess debugging when debugging programs that run in only one 
process. 


Advanced Concepts and Possible Errors 


The debugging configuration (default or multiprocess) is controlled entirely 
by the definition of DBG$PROCESS. If some of the processes in a job 
have different definitions of DBG$PROCESS, the resulting debugging 
configuration can be very confusing. | 


The value of DBG$PROCESS is checked when the kernel debugger is first 
invoked. 


Consider the following scenario: 


S$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 
S$ RUN TEST 


VAX DEBUG Version 5.4 
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DBG_1> SET BREAK/ACTIVATING; GO 
break at program activation in %PROCESS NUMBER 2 
DBG_2> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
1 SMITH interrupted TEST\%SLINE 50 
- 2 SMITH 1 activated SUB1\%LINE 71 
DBG_2> SPAWN DEFINE DBGSPROCESS DEFAULT ! Establish a default configuration 
DBG 2> SET BREAK SLINE 100;GO ! Assume that TEST creates a new process 


VAX DEBUG Version 5.4 


break at sLINE 100 in SPROCESS NUMBER 2 
DBG> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
* 3 SMITH 2 activated MYPROG\SLINE 10 
DBG 2> SHOW PROCESS/ALL 
Number Name Hold State Current PC 

1 SMITH interrupted TEST\SLINE 50 
* 2 SMITH 1. break SUB1\%SLINE 100 
DBG> 


Because of the re-assigment of DBG$PROCESS, there are two different 
main debuggers (two debugging sessions) in the job. Both debuggers use 
the same terminal for input and output. Therefore, the prompts and 
output lines from the two sessions are intermixed on the screen. (The 
effect is similar to what you see if you enter a DCL SPAWN/NOWAIT 
command, in that two processes are sharing the terminal). 


Generally, this mixed default and multiprocess configuration is not 
desirable. However, although potentially confusing, the configuration 
can be useful if you need to debug an experimental copy of a program 
without disturbing your primary debugging session, which has several 
processes connected to it. In such cases, use the SPAWN and ATTACH 
commands to control the activity of the subprocesses. 


10.2.9 System Requirements For Multiprocess Debugging 


Several users debugging multiprocess programs can place a load on a 
system. This section describes the resources used by the debugger, so that 
you or your system manager can tune your system for this activity. 


Note that the discussion covers only the resources used by the debugger. 
You might have to tune your system to support the multiprocess programs 
themselves. 


10.2.9.1 User Quotas 
Each user needs a PRCLM quota sufiicient to create an additional 
subprocess for the debugger, beyond the number of processes needed 
by the program. 


BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may 
need to be increased to account for the debugger subprocess as follows: 


e Each user’s ENQLM quota should be increased by at least the number 
of processes being debugged. 


e Each user’s PGFLQUOTA might need to be increased. If a user has an 
insufficient P@FLQUOTA, the debugger might fail to activate or cause 
"virtual memory exceeded" errors during execution. 
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e¢ Each user’s BYTLM and FILLM quotas might need to be increased. 
The debugger requires BYTLM and FILLM quotas sufficient to open 
each image file being debugged, the corresponding source files, and 
the debugger input, output, and log files. The debugger command SET 
MAX _SOURCE_FILES can be used to limit the number of source files 
kept open by the debugger at any one time. 


10.2.9.2 System Resources 
The kernel and main debugger communicate through global sections. The 
main debugger communicates with up to 8 kernel debuggers through a 
65-page global section. Therefore, the SYSGEN global-page and global- 
section parameters (GBLPAGES and GBLSECTIONS, respectively) might 
need to be increased. For example, if 10 users are using the debugger 
simultaneously, 10 global sections using a total of 650 global pages are 
required by the debugger. 
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Notes: 


This chapter describes features of the debugger that are specific to 
vectorized programs (programs that use VAX vector instructions). Use 
these features in addition to those explained in other chapters. 


The information in this chapter enables you to perform the following tasks: 


Display information about the availability and use of the vector 
processor on your system 


Control and monitor the execution of vector instructions with 
breakpoints, watchpoints, and so on 


Examine and deposit into the vector control registers (%VCR, 2VLR, 
and %VMR) and the vector registers (%V0 to %V15) 


Examine and deposit vector instructions and their operands 


Perform masked operations when examining vector registers or vector 
instructions to display only certain register elements or override the 
masking associated with a vector instruction 


When using the EXAMINE command, specify composite address 
expressions of a complex form that might be appropriate for a 
vectorized program 


Display the decoded results of vector floating-point exceptions 
Control synchronization between the scalar and vector processors 


Save and restore the current vector state when using the CALL 
command to execute a routine that might affect the vector state 


Display vector register data using a screen-mode display 


For additional information that is specific to a vectorized high-level 
language program, see the associated language documentation. For 
complete information about vector instructions and vector registers, see 
the VAX MACRO and Instruction Set Reference Manual. 


Compilers do not generate symbol-table data to associate 
vector registers with symbols declared in the program. 
Therefore, no symbolization is available for vector registers 
during a debugging session. Also, you can access a vector 
register only in scope 0 (the scope of the routine at the top of 
the call stack). 
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2 The examples in this chapter show how to access elements of 
a vector register using array syntax (for example, EXAMINE 
%V1(37)). This syntax is not supported for BLISS. In BLISS, use 
the SET LANGUAGE command to set the language temporarily 
to some other language, such as FORTRAN, then use the array 
syntax for that language. 


11.1 Obtaining Information About the Vector Processor 


The command SHOW PROCESS/FULL provides some information about 
the availability and use of the vector processor on your system. For 
example: 


DBG> SHOW PROCESS/FULL 


Vector capable: Yes 


Vector consumer: Yes Vector CPU time: O-00203217.18 
Fast Vector context switches: Q Slow Vector context switches: 0 
DBG> 


The Vector Capable field can have the following entries: 


Vector-Capable 
Entry Description 


Yes The VAX system has a vector processor, and it is available to 
the process that is running the program. 


No (protected) The VAX system has a vector processor, but the process 
running the program is denied access to the processor. 


VVIEF The VAX system does not have a vector processor. It is 
running the VAX Vector Instruction Emulation Facility (VVIEF). 
The VVIEF is available to the process that is running the 
program. 


No The VAX system does not have an active vector processor, 
and the VVIEF is not loaded on the system. 


11.2 Controlling and Monitoring the Execution of Vector Instructions 
The following sections explain how to perform the following tasks: 


e Execute the program to (step to) either the next vector instruction or 
any one of a set of specified vector instructions. 


e Set breakpoints and tracepoints that trigger either on any vector 
instruction or on any one of a set of specified vector instructions. 


e Set watchpoints to monitor changes in vector registers. 
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11.2.1 Executing the Program to the Next Vector Instruction 


To execute the program to the next vector instruction encountered in the 
program, enter the command STEP/VECTOR_INSTRUCTION. 


You can also execute the program to the next vector instruction 
whose opcode is in a list of opcodes by using the command STEP 
JAINSTRUCTION=(opcode[,.../). For example: 


DBG> STEP/INSTRUCTION= (VLDL, VSTL, MOVL) 


The SET STEP command enables you to change the default unit of 
execution of the STEP command: 


e Enter the command SET STEP VECTOR_INSTRUCTION to make the 
STEP command execute the program to the next vector instruction by 
default. 


e Enter the command SET STEP INSTRUCTION=(opcodef,.../) to make 
the STEP command execute the program to the next instruction that 
is in the list of opcodes (including a vector instruction) by default. 


11.2.2 Setting Breakpoints and Tracepoints on Vector Instructions 


To set a breakpoint (or a tracepoint) that triggers whenever a vector 
instruction is encountered in the program, enter the command 

SET BREAK/VECTOR_INSTRUCTION (or SET TRACE/VECTOR_ 
INSTRUCTION). 


To cancel such breakpoints or tracepoints, enter the command CANCEL 
BREAK/VECTOR_INSTRUCTION or CANCEL TRACE/VECTOR_ 
INSTRUCTION. 


You can also set breakpoints and tracepoints on one or more specific vector 
instructions by using the qualifier INSTRUCTION=(opcode/,.../) with the 
SET BREAK and SET TRACE commands. For example: 


DBG> SET BREAK/INSTRUCTION= (VVADDL, VVLEQL) 


To cancel such breakpoints and tracepoints, enter the command CANCEL 
BREAK/INSTRUCTION or CANCEL TRACE/INSTRUCTION. 


11.2.3. Setting Watchpoints on Vector Registers 


You can set watchpoints on the vector registers (VO to V15) and on the 
vector control registers (VCR, VLR, and VMR). Section 11.3.1 identifies 
these registers and their built-in debugger symbols. 


These watchpoints are treated like static watchpoints in that, once set, the 
watchpoint is active until you cancel it explicitly. 


In the following example, a watchpoint is set on register VCR: 


DBG> SET WATCH %VCR 
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In the case of VMR and VO to V15, you can set a watchpoint either on 
the register aggregate (that is, on all elements of the register), on an 
individual register element, or on a range of elements (a slice). Use the 
same technique that you use to set a watchpoint on an array variable. 
(See Section 3.6.) 


For example, the following command sets a watchpoint that triggers if any 
element of register V5 changes: 


DBG> SET WATCH %V5 


The following command sets a watchpoint that triggers if element 37 of V2 
changes (FORTRAN array syntax): 


DBG> SET WATCH %V2 (37) 


The following command sets a watchpoint that triggers if any element of 
V2 in the range from element 5 to 13 changes: 


DBG> SET WATCH %V2 (5:13) 


11.3 Examining and Depositing into Vector Registers 


The following sections explain how to examine and deposit into the vector 
control registers (VCR, VLR, and VMR) and the vector registers (V0 to 
V15). 


11.3.1. Specifying the Vector Registers and Vector Control Registers 


The VAX architecture provides 16 vector registers (VO to V15) and 3 
vector control registers (VCR, VLR, VMR). When referencing any of these 
registers in a debugger command, use the following built-in symbols (the 
register name preceded by a percent sign (% )). 


Symbol Description 


%VO... %V15 Vector registers (VO ... V15) 


%VCR Vector count register (VCR) 
%VLR Vector length register (VLR) 
%VMR Vector mask register (VMR) 


As with all debugger register symbols, you can omit the percent sign (%) 
prefix if your program has not declared a symbol with the same name. 


11.3.2 Examining and Depositing into the Vector Count Register (VCR) 
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The vector count register (VCR) specifies the length of the offset vector 
generated by the IOTA instruction. 


The value of VCR is an integer from 0 to 64. By default, the debugger 
treats VCR as a longword integer. Although you can deposit values 
greater than 64 into VCR, the debugger issues a diagnostic message that 
the value is out of bounds in such cases. 
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The following command sequence shows how to manipulate the value of 


VCR: 
DBG> EXAMINE %VCR 
O\SVCR: 8 


DBG> DEPOSIT %VCR = 4 
DBG> EXAMINE %VCR 
O\SVCR: 4 

DBG> 


11.3.3 Examining and Depositing into the Vector Length Register (VLR) 


The vector length register (VLR) limits the highest element of a vector 
register that is processed by a vector instruction. The value of VLR is an 
integer from 0 to 64. This value specifies the number of register elements 
that are processed, starting with element 0. 


In the context of a debugging session, the current value of VLR limits the 
highest element of a vector register that you can access with an EXAMINE 
or DEPOSIT debugger command. 


The following command sequence shows how to manipulate the value of 
VLR to examine different numbers of elements of the vector register V1: 


DBG> EXAMINE %VLR 


O\SVLR: 4 

DBG> EXAMINE $V1 

O\SV1 
(0): 12 
(1) 3 
(2): 138 
Co) 5a: 


DBG> DEPOSIT <VLR = 3 
DBG> EXAMINE %SVLR 


O\SVLR: 3 
DBG> EXAMINE %V1 
O\SV1 
(0): 12 
(i) 3 
(2): 138 
DBG> 


You cannot access a register element outside the range from 0 to VLR-1. 
In the following example, the EXAMINE command specifies element 7 of 
register V1, which is out of bounds (FORTRAN array syntax): 


DBG> EXAMINE %VLR 

O\SVLR: 3 

DBG> EXAMINE %V1 (7) 

%SDEBUG-~E-VECTSUBRNG, vector register subscript out of bounds, 
bounds are 0..2 

DBG> 


By default, the debugger treats VLR as a longword integer. Although 
you can deposit values greater than 64 into VLR, the debugger issues a 
diagnostic message that the value is out of bounds in such cases. 
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11.3.4 Examining and Depositing into the Vector Mask Register (VMR) 
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The vector mask register (VMR) specifies a mask (a bit pattern) that a 
vector instruction uses in order to operate on only certain elements of a 
vector register operand. A masked vector instruction cannot operate on an 
element of a vector register that is masked by VMR. 


VMR has 64 bits (1 quadword), numbered 0 to 63. Each bit corresponds 
to an element of a vector register. The value of a particular bit (0 or 1) 
determines whether the corresponding register element is operated on 
during a masked operation. 


Masked operations are explained in Section 11.4.1 and Section 11.5. This 
section describes only how to display and change the value of VMR. 


To examine one or more specific elements (bits) of VMR, use the same 
technique that you use to examine an array variable. (See Section 4.2.3.) 


For example, the output of the following command shows that bit 5 of 
VMR is set (FORTRAN array syntax): 


DBG> EXAMINE %VMR(5) 
O\SVMR (5): 1 
DBG> 


The following command displays the values of bits 4 to 6 of VMR. Bits 4 
and 5 are set, and bit 6 is clear: 


DBG> EXAMINE %VMR(4: 6) 


O\SVMR 
(4): L 
(5): 1 
(6): 0 
DBG> 


By default, when you examine VMR without specifying subscripts, the 
debugger displays the value of the register as a quadword integer in 
hexadecimal format, to reduce the size of the output display. For example: 


DBG> EXAMINE %VMR 
O\SVMR 

(0): OFFFFFFF FFFFFFFF 
DBG> 


By specifying the command EXAMINE/BIN %VMR or the command 
EXAMINE %VMR(0:63), you can display the value of each bit of VMR in a 
64-row array format. 


As with an array variable, you can deposit a value into one bit of VMR at 
a time. For example: 


DBG> EXAMINE %VMR (37) 


O\SVMR (37): Ed 

DBG> DEPOSIT %VMR(37) = 0 
DBG> EXAMINE 3VMR(37) - 
O\S3VMR (37): 0 

DBG> 
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You can also deposit a quadword integer value into the entire aggregate by 
using the command DEPOSIT/QUADWORD. For example: 


DBG> DEPOSIT/QUADWORD %VMR = %HEX OFFFFF 
DBG> EXAMINE %VMR 
O\SVMR 
(0): 00000000 OOOFFFFF 
DBG> 


11.3.5 Examining and Depositing into the Vector Registers (VO to V15) 


There are 16 vector registers, designated VO to V15. Each of the vector 
registers has 64 elements, numbered 0 to 63, and each element has 64 bits 
(one quadword). 


To examine one or more elements of a vector register, use the same 
technique that you use to examine an array variable. (See Section 4.2.3.) 
The examples in this section use FORTRAN array syntax: 


DBG> EXAMINE <%V3 !'Examine all elements of V3 
DBG> EXAMINE %V3 (27) 'Examine element 27 of V3 

DBG> EXAMINE V3 (3:14) !'Examine elements 3 to 14 of V3 
DBG> EXAMINE %V0O (2) ,%V3(1:4) iExamine element 2 of VO and 


'elements 1 to 4 of V3 


The values of register elements are displayed in an indexed format similar 
to that used for an array variable. For example, the following command 
displays the values of elements 1 to 3 of register V1: 


DBG> EXAMINE %V1 (1:3) 


O\SV1 
(1): 5 
(2): 138 
(3): 51 
DBG> 


Note that you cannot examine a range of vector registers. For example, 
the following commands are invalid: 


DBG> EXAMINE %V0:%V3 
DBG> EXAMINE %V2 (7) :%V3 (12) 


As with an array variable, you can deposit a value into only one element of 
a vector register at a time. For example, the following command deposits 
the integer value 8531 into element 9 of VO: 


DBG> DEPOSIT %V0O(9) = 8531 


The current value of the vector length register (VLR) limits the highest 
register element that you can examine or deposit into. (See Section 11.3.3.) 
Therefore, the following commands are equivalent: 


DBG> EXAMINE %V1 
DBG> EXAMINE «V1 (0: %3VLR-1) 


The expression 0:%VLR-1 specifies the range of register elements that are 
denoted by the current value of VLR. 
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By default, the debugger treats each element of a vector register as a 
longword integer and displays the value in the current radix. For example: 


DBG> EXAMINE %V3 (27) 


O\SV3 (27): 5983 

DBG> DEPOSIT %V3(27) = 3625 
DBG> EXAMINE V3 (27) 

O\S$V3 (27): 3625 

DBG> 


However, note that a register value that is examined in the context of a 
vector instruction (that is, as an instruction operand) is displayed in the 
data type that is appropriate for the instruction. (See Section 11.4.1.) 


To display the full (quadword) value of an element of a vector register as 
a quadword integer, use the command EXAMINE/QUADWORD. Similarly, 
to deposit a quadword integer value into a register element, use the 
command DEPOSIT/QUADWORD. 


You can also use any of the other type qualifiers associated with the 
EXAMINE and DEPOSIT commands (for example, /FLOAT) to override 
the default type. For example: 


DBG> EXAMINE %V5 (2) 


O\SV5 (2) : 0 

DBG> EXAMINE/D FLOAT %V5(2) 
O\SV5 (2): 0.0000000000000000 
DBG> 


You can use register symbols in language expressions, subject to the 
restrictions on using aggregate data structures in language expressions. 
(See Section 4.1.5.1.) For example, the following expression is valid 
(FORTRAN syntax): 


DBG> EVALUATE %V0(4) .EQ. %V1(4) 


However, the following expression is not valid because more than one 
register element is specified: 


DBG> EVALUATE sVO .EQ. V1 


11.4 Examining and Depositing Vector Instructions 
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The techniques for manipulating vector instructions include all of those 
used for scalar instructions (described in Section 4.3) and additional 
techniques specific to vector instructions: 


e You can use a screen-mode instruction display to present the scalar 
and vector instructions decoded from the instruction stream of your 
program. 


¢ You can execute your program at the vector instruction level by using 
commands such as the following: 


STEP/VECTOR_INSTRUCTION 
STEP/AINSTRUCTION=(opcode/,.../) 

SET STEP VECTOR_INSTRUCTION 
SET STEP INSTRUCTION=(opcodef..../) 
SET BREAK/VECTOR_INSTRUCTION 
SET BREAK/INSTRUCTION=(opcode!,.../) 
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e You can use the command EXAMINE/OPERANDS to display the 
instruction at the current PC value, including any operand information 
contained in vector registers. In addition, the qualifiers /TMASK 
and /FMASK enable you to simulate the effect of the vector mask 
register (VMR) or override any masking associated with the examined 
instruction so that you can hide or display specific register elements. 


e You can deposit a vector instruction at a particular memory address in 
your program. 


Whether you are examining or depositing vector instructions, the debugger 
correctly processes the vector instruction qualifiers according to the 
instructions to which they apply. The following table summarizes the 
functions of these qualifiers. See the VAX MACRO and Instruction Set 
Reference Manual for complete information about their use. 


Instruction 
Qualifier | Description 


/U Enable floating underflow (vector floating-point instructions) 

IN Enable integer overflow (vector integer instructions) 

/M Modify intent (VLDx and VGATHx instructions) 

/0 Perform masked operations only on elements for which the VMR bit is 0 
/1 Perform masked operations only on elements for which the VMR bit is 1 


11.4.1. Examining Vector Instructions and Their Operands 


When you examine a program location that contains a vector instruction, 
the debugger decodes that instruction and translates it and its operands 
into their VAX MACRO assembler form, with the following restrictions. 
(See the VAX MACRO and Instruction Set Reference Manual for details 
about instruction opcodes.) 


e Ifthe vector control word is not encoded using either immediate or 
short-literal mode, the debugger cannot translate the opcode and, 
therefore, displays the instruction and its operands in their VAX vector 

' architectural form rather than their VAX MACRO assembler form. 


e If the VAX opcode is VSMERGEx, the debugger displays the 
instruction mnemonic as VOSMERGE rather than VSMERGEF, 
VSMERGED, or VSMERGEG. In this case, a literal src.rg operand 
is displayed as a quadword integer in the current radix. 


The command EXAMINE/OPERANDS .%PC enables you to display the 
instruction at the current PC value and its operands. (See Section 4.3.1.) 
When you examine a vector instruction with this command, the values of 
any vector register operands are displayed as for an array variable. For 
example (FORTRAN array syntax): 
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DBG> EXAMINE/OPERANDS .%PC 
PROGSMAIN\SLINE 81+19: VSTL V0O,W*-572 (FP) ,S*#4 
VO contains: 

O\3V0O(0): 137445504 

O\SV0O(1): 137445504 

O\3V0 (2): 137445504 


W*-572 (FP) 2145991456 contains 2 
DBG> 


As with scalar instructions, operand values are displayed in the data type 
that is appropriate for the examined instruction. 


When you use the command EXAMINE/OPERANDS, the display of 
register elements depends on the following factors: 


e The current value of VLR. The highest element of a vector register 
that is operated on (and, therefore, displayed) is limited by the value 
of VLR. 


¢ Whether the examined instruction is performing a masked operation. 
In an unmasked operation, all register elements (up to VLR-1) are 
displayed. A masked operation is indicated by the presence of the /1 or 
/O instruction qualifier. For example: 


VVADDF/1 v0O,V1,V2 


In a masked operation, only the elements that correspond to the 
set or clear bits of VMR are operated on (depending on whether the 
instruction qualifier is /1 or /0, respectively). 


These concepts are illustrated in the following two examples, which show 
an unmasked and a masked register-to-register operation, respectively. 


In the next example, the examined instruction, VVADDF, is performing an 
unmasked operation so that the current value of VMR is irrelevant. All 
elements from 0 to 5 are displayed: 


DBG> EXAMINE %SVLR 


O\SVLR: 6 
DBG> EXAMINE %VMR(0:5) 
O\SVMR 

(O): 1 

Ca) s @) 

(2): sl: 

(3): 0 

(4): iD 

C5). 0 
DBG> EXAMINE/OPERANDS .%PC 
PROGSMAIN\SLINE 12: VVADDF V0O,V1,V2 


VO contains: 
O\%V0O(0): 7.0000000 
O\SV0O(1): 7.0000000 


O\3V0 (5): 7.0000000 
Vl contains: 

O\%SV1(0): 4.0000000 

O\SV1(1): 4.0000000 


O\$V1(5): 4.0000000 
V2 contains: 
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O\SV2(0): 5.0000000 
O\SV2(1): 5.0000000 
O\SV2(5): 5.0000000 


DBG> 


In the next example, the same VVADDF instruction is performing a 
masked operation. The instruction qualifier /1 specifies that elements that 


match the set bits (bit value 1) in VMR are operated on: 


DBG> EXAMINE %VLR 
O\SVLR: 6 
DBG> EXAMINE %VMR(0:5) 
O\SVMR 
(0): 1 
(1): 0 
(2): 1 
(3)¢% 0 
(4): ah 
(3S): 0 
DBG> EXAMINE/OPERANDS .%PC 
PROGSMAIN\SLINE 12: VVADDF/1 v0O,V1,V2 
VO contains: 
O\SVO(0): 7.0000000 
O\SVO0(2): 7.0000000 
O\S$V0 (4): 7.0000000 
V1 contains: 
O\%SVO0 (0): 4.0000000 
O\SVO (2): 4.0000000 
O\S$V0 (4): 4.0000000 
V2 contains: 
O\%V0 (0): 5.0000000 
O\$V0(2): 5.0000000 
O\S$V0 (4): 5.0000000 


DBG> 


The next example shows a masked operation that loads data from memory 
to a vector register. Comments, keyed to the callouts, follow the example. 


DBG> EXAMINE 


SVLR 


O\SVLR: 6 
DBG> EXAMINE %VMR(0:5) 
O\SVMR 
(0): 1 
eee. 0 
(2): 1 
(3): 0 
(4): 1 
(5): 0 
DBG> EXAMINE/OPERANDS .%PC @ 
PROGSMAIN\S%LINE 31+12: VLDL/1  ARR+8,#4,vo @ 


PROGSMAIN\ARR (3) 


VO contains: 


O\SVO (0) : 
O\SV0O (2): 
O\SVO (4): 


(address 1024) contains 35 


DBG> EXAMINE ARR(1:8) ®@ 


PROGSMAIN\ARR 
(1): 9 
(2): Ld 
(3): oO 
(4): 73 
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(5) 81 

(6): 6 

(7): a 

(8): 49 
DBG> 


Figure 11-1 Masked Loading of Array Elements from Memory into a 
Vector Register 


Instruction: VLDL/1 ARR+8, #4,V0 





ZK-1937A-—GE 


The comments that follow refer to the callouts in the previous example: 


@ The EXAMINE/OPERANDS command shows that a VLDL instruction 
is about to be executed. The instruction will load longword-integer 
data from array ARR, starting at ARR+8 bytes, into register VO, as 
illustrated in Figure 11-1. Figure 11-1 shows the contents of VO after 
the instruction has been executed. Note that array ARR is indexed 
1..n, not 0..n-1 (FORTRAN example). 


@ The stride value (#4) of the VLDL instruction specifies the number of 
bytes between the start addresses of array elements. 


© The instruction operand ARR+8 denotes the start of array element 3, 
ARR(3). The EXAMINE/OPERANDS command displays only the first 
element of array ARR that is operated upon (see item 9). 
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@ The current values of VLR and VMR will cause the VLDL instruction 
to load the contents of array elements ARR(3), ARR(5), and ARR(7) 
into register elements VO0(0), VO(2), and V0(4), respectively. The 
EXAMINE/OPERANDS command shows the contents of VO before the 
instruction has been executed. 


® For reference, the command EXAMINE ARR(1:8) displays the full 
range of array elements that are associated with the load operation. 


11.4.2 Depositing Vector Instructions 


The techniques for depositing VAX scalar instructions also apply to 
depositing vector instructions. (See Section 4.3.2.) For example, the 
following command deposits a masked VVMULF vector instruction at the 
current PC address: 


DBG> DEPOSIT/INSTRUCTION .$PC = "VVMULF/0 V2,V3,V7" 


Note the following additional information when depositing vector 
instructions. (See the VAX MACRO and Instruction Set Reference Manual 
for details about instruction opcodes.) 


e The regnum.rw operand of the MxVP and VSYNC instructions is 
generated as a short literal. 


e Do not specify a vector control word when depositing a vector 
instruction. The debugger constructs the vector control word based 
on the instruction and instruction qualifiers, if any, and encodes it 
using immediate mode. 


e The value of an immediate argument of a VSMERGEx instruction is 
interpreted according to the data type associated with that instruction. 
For example, the src argument for a VSMERGEF instruction is 
interpreted as a F_floating value, and so on. For VSMERGE without a 
type suffix, the debugger interprets a literal src operand as a quadword 
integer in the current radix. 


11.5 Using a Mask When Examining Vector Registers or Instructions 


Section 11.4.1 explains how the command EXAMINE/OPERANDS .%PC 
displays vector instruction operands, depending on whether or not the 
operation is masked by VMR. 


This section explains how to specify an arbitrary mask in order to simulate 
or override the effect of VMR and obtain the following results: 


e Display only certain elements of a vector register or of an array in 
memory 


e Override the operand masking (if any) that might be associated with 
an examined instruction 
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Note: 


You specify a mask by using the /TMASK or /FMASK qualifier with the 
EXAMINE command. 


The remainder of this section describes use of the /TMASK and 
/FMASK qualifiers when examining vector registers. Unless 
indicated otherwise, the discussion also applies to use of these 
qualifiers when examining memory arrays. 


The /TMASK qualifier applies the EXAMINE command only to the 
elements of the examined register that correspond to the set bits (bit 
value: 1) of the mask. The /FMASK qualifier applies the EXAMINE 
command only to the elements that correspond to the clear bits (bit value: 
0) of the mask. 


The current value of VLR limits the highest element of a vector register 
that you can examine. But the value of VLR does not affect examining an 
array in memory. 


You can optionally specify a mask (in the form of a mask address 
expression) with the /T[MASK and /FMASK qualifiers: 


e Section 11.5.1 describes use of these qualifiers with the default mask, 
which is VMR. 


e Section 11.5.2 describes use of these qualifiers with some arbitrary 
slice of VMR as the mask. 


¢ Section 11.5.3 describes use of these qualifiers with a mask other than 
VMR. 


11.5.1 Using VMR as the Default Mask 
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By default, if you do not specify a mask with the EXAMINE/TMASK or 
EXAMINE/FMASK command, VMR is used as the mask. That is, the 
EXAMINE command is applied only to the elements of the vector register 
that correspond to the set bits (in the case of /TMASK) or clear bits (in the 
case of /EFMASK) of VMR. 


In the examples that follow, VLR has the value 6 and VMR(0:VLR—1) has 
the following set of values: 


DBG> EXAMINE %$VMR(0:%VLR-1) 

O\SVMR 
(O): 
(1): 
(2): 
(3) 
(4): 
(5): 

DBG> 


OrOoOrROOF 


The following command displays the value of V3 without using a mask. 
All elements of V3 from 0 to VLR—1 are displayed: 
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DBG> EXAMINE %V3 


O\SV3 
(0): 17 
(iy £38 
(2): 3 
(3): 9 
(4): Dil. 
(5): 252 

DBG> 


The following command displays the elements of V3 (in the range from 0 
to VLR-1) for which VMR(@) has the value 1: 


DBG> EXAMINE/TMASK $%V3 


O\%V3 
(0): 17 
(2): 3 
(4): 51 
DBG> . 


The following command displays the elements of V3 (in the range from 0 
to VLR-1) for which VMR() has the value 0: | 


DBG> EXAMINE/FMASK %V3 


O\SV3 
(1): 138 
(3): 9 
(5) 252 
DBG> 


In the following example, the /FMASK qualifier is used when examining 
an instruction and its vector-register operands. The EXAMINE 
/OPERANDS/FMASK command displays the register-operand elements 
(in the range from 0 to VLR-1) for which VMR(z) has the value 0: 


DBG> EXAMINE/OPERANDS/FMASK .3PC 
PROGSMAIN\SLINE 3414+16: VVEQLL VO,V1 
VO contains: 

O\SVO(1): O 

O\SV0(3): O 

O\SVO(5): O 


Vl contains: 
O\$V1(1): 
O\S$V1(3): 
O\SV1(5): 


OO Oo 


DBG> 


11.5.2 Using a Slice of VMR as the Mask 


If you specify a slice of VMR with the EXAMINE/TMASK or EXAMINE 
/FMASK command, the output is displayed according to the following 
conventions: 


1. The number of mask elements specified limits the number of register 
element that you can examine. For example: 
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11.5.3 Using a Mask Ot 
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DBG> EXAMINE %VLR 
O\SVLR: 12 
DBG> EXAMINE %VMR(3:5) 


O\SVMR 
(3) 2 l: 
(4): 1 
(5): 1 
DBG> EXAMINE/TMASK=(%$VMR(3:5)) %V0(3:10) 
O\SVO 
€3,)-% 9 
(4): 51 
(5): 252 
DBG> 


Note the use of parentheses when specifying a mask with the /TMASK 
qualifier. 


The lowest specified element of the mask is applied to the lowest 
specified element of the register. For example, EXAMINE/TMASK 
%V0(4:7) applies VMR(0) to V0(4), VMR(1) to V0(5), and so on. If the 
lowest specified elements of the mask and register do not match, the 
debugger lists both the mask elements and the register elements that 
are operated on and issues a message. For example: 


DBG> EXAMINE %VLR 
O\SVLR: 12 
DBG> EXAMINE %VMR(4:7) 


O\3VMR 
(4): 1 
(5)2 0 
(6): 1 
(7): 1 


DBG> EXAMINE/TMASK=(%VMR(4:7)) %V0(3:10) 
SDEBUG-I-MASKMISMATCH, mask/target subscripts do not match, 
displaying mask 

O\SVO 

SVMR (4): 

V0 (3): 

SVMR (6) : 

SV0 (5): 25 

SVMR (7): 

SVO0 (6): 3) 
DBG> 


OrMNF OF 


her than VMR 


If you specify a mask address expression other than VMR with the 
EXAMINE/TMASK or EXAMINE/FMASK command, the value at that 
address is used as the mask, subject to the following conventions: 


If the mask address expression denotes a Boolean array, its values 
are used as the mask in the same basic way that VMR is used in 
the default case. In the following example, BOOL_ARR, a 4-element 
Boolean array variable, is used as the mask: 
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DBG> EXAMINE %@VLR 
O\SVLR: 6 

DBG> EXAMINE BOOL ARR 
PROGSMAIN\BOOL_ARR 


(0): 0 
CL) 0 
(2): ug 
(3) 0 


DBG> EXAMINE/FMASK=(BOOL ARR) %VO 
SDEBUG-I~MASKNOTVMR, mask used is not %VMR, displaying 
specified mask 


O\SVO 
BOOL ARR(0): 0 
V0 (0): 17 
BOOL ARR(1): 0 
SV0 (1): 138 
BOOL ARR (3): 0 
SV0 (3): 9 

DBG> 


As shown in the example, when you use a mask other than VMR, the 
debugger displays both the mask elements and the register elements 
that are operated on and issues a message. 


e If the mask address expression denotes a non-Boolean array, the 
least significant bit of each array element is used as the mask for the 
corresponding element of the register. 


e Ifthe mask address expression denotes a Boolean scalar type, its 
value is used as the mask for the first element of the register. No 
other elements are examined. In the following example, BOOL_VAR, a 
single-element Boolean variable, is used as the mask: 


DBG> EXAMINE BOOL VAR 

PROGSMAIN\BOOL VAR: 1 

DBG> EXAMINE/TMASK=(BOOL VAR) %V0 

SDEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying 
specified mask 


O\%SVO 
BOOL VAR: 1 
5V0 (0): L7 
DBG> 


e Ifthe mask address expression denotes any other type, its least 
significant bit value is used as the mask for the first element of the 
register. No other elements are examined. 


e The number of mask elements specified limits the number of register 
elements that you can examine, as when the mask is VMR (see 
Section 11.5.2). 


e¢ For a multi-element mask, the lowest specified element of the mask 
is applied to the lowest specified element of the register, as when the 
mask is VMR (see Section 11.5.2). | 
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11.6 Examining Composite Vector Address Expressions 


When using the EXAMINE command, you can specify various forms of 
composite address expressions—expressions that include byte offsets from 
a given address. For example, if X is an integer variable, the following 
EXAMINE command displays the value currently stored at the memory 
location that is 6 bytes beyond the address of X: 


DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 


The examples in this section show how to specify composite address 
expressions of a form that might be appropriate for a vectorized program. 


The next example shows how you might verify the effect of a VSCATL 
instruction. The instructions shown are decoded from a FORTRAN 
program. Comments, keyed to the callouts, follow the example. 


DBG> EXAMINE %VLR 
O\%SVLR: 5 
DBG> EXAMINE/OPERANDS .3Pc @ 
PROGLSMAIN\SLINE 9+32: VSCATL  V7,W*-804(R11),V9 
V7 contains: 
O\$V7(0): 11 @ 
O\SV7(1): 13 
O\SV7(2): 15 
O\$V7(3): 17 
O\3V7(4): 19 


W*-804 (R11) PROGISMAIN\ARRX(1) (address 1820) contains 0 3] 

V9 contains: 

O\3v9(0): 0 @ 

O\SV9(1): 8 

O\SV9(2): 16 

O\S$V9(3): 24 

O\%V9 (4): 32 
DBG> SHOW SYMBOL/TYPE ARRx @ 
data PROGISMAIN\ARRX 
array descriptor type, 1 dimension, bounds: [1:200], size: 800 bytes 
cell type: atomic type, longword integer, size: 4 bytes 
DBG> EXAMINE ARRX(1) + .%V9(0:%VLR-1) . 
PROGISMAIN\ARRX (1): 
PROG1SMAIN\ARRX (3): 
PROGISMAIN\ARRX (5): 
PROG1SMAIN\ARRX (7) : 
PROG1SMAIN\ARRX (9) : 
DBG> STEP/INSTRUCTION 
stepped to PROGISMAIN\$LINE 9+40: MOVZBL  1*#64,AP 
DBG> EXAMINE ARRX(1) + .%3V9(0:%VLR-1) 


Boo0c0o0oc 


PROG1$MAIN\ARRX (1) : 11 
PROGISMAIN\ARRX (3) : 13 
PROG1SMAIN\ARRX (5) : 15 
PROGISMAIN\ARRX (7) : i 
PROG1SMAIN\ARRX (9) : 19 
DBG> 
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The comments that follow refer to the callouts in the previous example: 


@ The EXAMINE/OPERANDS command shows that a VSCATL 
instruction is about to be executed. The instruction will transfer 
longword-integer (4-byte) data from register V7 into memory locations. 
These locations are determined by adding offset values, contained in 
register V9, to a base address. 


Register V7 contains the longword-integer values to be transferred to 
memory. 


The base address specified as an operand to the VSCATL instruction is 
symbolized as ARRX(1), which denotes element 1 of array ARRX. 


Register V9 contains the offset from the base address, in bytes, of each 
target vector element in memory. 


The SHOW SYMBOL/TYPE command indicates that ARRX is an array 
of contiguous longword integers. 


The EXAMINE command displays the values of the target vector 
elements in memory. The address expression specified uses the offset 
values contained in register V9 to set the start address of successive 
vector elements in memory, relative to ARRX(1), the base address. The 
debugger symbolizes the locations of vector elements in memory in 
terms of the elements of array ARRX. In this example, vector elements 
begin every 8 bytes, coinciding with every other element of array 
ARRX. Because the VSCATL instruction has not yet been executed, all 
of the vector elements in memory contain the value zero. 


@ The STEP/INSTRUCTION command executes the VSCATL instruction 
and suspends execution at the next instruction, MOVZBL. 


© As in item ©, the EXAMINE command displays the values of the 
target vector elements in memory. Now the contents of memory show 
that the values have been transferred from register V7. 


o 9 6 8 


The next example shows how to specify a more complex vector address 
expression with the EXAMINE command. 


Assume that array ARRZ has contiguous quadword-integer (8-byte) 
elements. The fourth EXAMINE command in the example displays the 
values of vector elements in memory, starting at element ARRZ(1). As 

in the previous example, the debugger symbolizes the locations of vector 
elements in terms of the array elements. The location of successive vector 
elements relative to ARRZ(1) is computed by adding the values contained 
in registers V1 and V8 to specify a combined offset for a particular 
element. The order in which vector elements are displayed is determined 
by cycling through all the values in the last specified register (V3(0:2)) for 
each value in the first specified register (V1). In this example, the values 
of all vector elements are zero. 
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DBG> EXAMINE %VLR 


O\SVLR: 4 
DBG> EXAMINE %V1 
O\SV1 
(0): 0) 
(1) 4 
(2) 2 8 
(3): 12 
DBG> EXAMINE %V3 
O\SV1 
(0): 0 
(1): 8 
(2): 16 
(3): 24 


DBG> EXAMINE ARRZ(1) + .%V1(0:3) + .%$V3(0:2) 
PROG4SMAIN\ARRZ (1): ! ARRZ(1)+0+0 
PROG4SMAIN\ARRZ (2): 1 ARRZ(1)+0+8 
PROG4SMAIN\ARRZ (3): | ARRZ (1)+0+16 
PROG4SMAIN\ARRZ (1) +4: ! ARRZ(1)+4+0 
PROG4SMAIN\ARRZ (2) +4: ! ARRZ(1)+4+8 
PROG4SMAIN\ARRZ (3) +4: ! ARRZ(1)+4+16 
PROG4SMAIN\ARRZ (2): 1 ARRZ (1) +8+0 
PROG4SMAIN\ARRZ (3): ! ARRZ(1)+8+8 
PROG4SMAIN\ARRZ (4) : ! ARRZ(1)+8+16 
PROG4SMAIN\ARRZ (2) +4: ! ARRZ(1)+12+0 
PROG4SMAIN\ARRZ (3) +4: 1 ARRZ (1) +12+8 
PROG4SMAIN\ARRZ (4) +4: ! ARRZ (1) +12+16 
DBG> 


oooooo0o 000 00 0 


11.7 Displaying the Results of Vector Floating-Point Exceptions 
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When a vector instruction causes a floating-point exception in a vector 
element, the exception result is encoded into the corresponding element of 
the destination register. 


In such cases, you can use the EXAMINE/FLOAT command to display 


the decoded exception message in the associated register element. This 


technique enables you to identify a floating-point exception that is still 
pending delivery, as illustrated in Section 11.8. The following example 
shows that a vector instruction caused a floating divide-by-zero exception 
in element 2 of register V5: 


DBG> EXAMINE/FLOAT %V5 


O\SV5. 
(0): 297.2800 
(1): 87.41499 
(2): Reserved operand, encoded as floating divide by zero 
(3) 173.8650 
DBG> 


If the program copies values from vector registers into memory, you can 
apply the EXAMINE/FLOAT command to the memory location and display 
the decoded information, as you would for a vector register. 


The following table identifies the decoded debugger message for each type 
of vector floating-point exception. 
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Exception Debugger Message 

Floating underflow Reserved operand, encoded as floating underflow 
Floating divide by Reserved operand, encoded as floating divide by zero 
zero 

Floating reserved Reserved operand, encoded as floating reserved operand 
operand 

Floating overflow Reserved operand, encoded as floating overflow 


11.8 Controlling Scalar-Vector Synchronization 


To achieve high performance, the VAX scalar and vector processors operate 
concurrently as much as possible. The scalar processor passes any vector 
instructions to the vector processor and then continues executing scalar 
instructions while the vector processor executes vector instructions. 


In some cases, the operation of the two processors must be synchronized to 
ensure correct program results. By using synchronizing instructions such 
as SYNC, MSYNC, and VSYNC, the program forces certain operations to 
complete before others are initiated. See the VAX MACRO and Instruction 
Set Reference Manual for more information about these instructions and 
scalar-vector synchronization. 


If the program has been vectorized by the compiler (for example, the 
VAX FORTRAN compiler), the necessary synchronizing instructions are 
automatically generated. However, VAX MACRO programmers need to 
code synchronizing instructions explicitly. 


By default, the debugger does not force scalar-vector synchronization 
during program execution except for its own internal purposes. The 
program executes as if it were running without debugger control, and 
synchronization is controlled entirely by the program. This default 
mode of operation is established by the command SET VECTOR_MODE 
NOSYNCHRONIZED. 


When you use the debugger in the default, nonsynchronized vector mode, 
certain vector operations might be in an interrupted state when program 
execution is suspended at a breakpoint, watchpoint, or at the completion 
of a STEP command. For example: 


e An exception caused by a vector instruction might be pending delivery. 


e An operation that transfers data between vector registers and scalar 
memory might not have completed. Therefore, examining the contents 
of memory or vector registers might yield unpredictable results. 


To eliminate potential confusion in such cases, enter the command 
SYNCHRONIZE VECTOR_MODE. It forces immediate synchronization 
between the scalar and vector processors. Entering this command is 
equivalent to issuing a SYNC and an MSYNC instruction at the location 
in the program at which execution is suspended. The effect is as follows: 


e Any exception that was caused by a vector instruction and was still 
pending delivery is immediately delivered. Note that forcing the 
delivery of a pending exception triggers an exception breakpoint or 
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tracepoint (if one was set) or invokes an exception handler (if one is 
available at that location in the program). 


e Any read or write operation between vector registers and either the 
general registers or memory is completed immediately—that is, any 
vector memory instruction that was still being executed completes 
execution. 


The following MACRO example shows the effect of the SYNCHRONIZE 
VECTOR_MODE command. Comments, keyed to the callouts, follow the 
example. 


DBG> step @ 
stepped to .MAIN.\SUB\%SLINE 99 


99; VVDIVD V1,V0,V2 
DBG> STEP 
stepped to .MAIN.\SUB\%SLINE 100 

100: CLRL RO 

DBG> EXAMINE/FLOAT %V2 
O\SV2 

[O]: 13.53400 

Pos Reserved operand, encoded as floating divide by zero 


[2]: 247.2450 


DBG> SYNCHRONIZE VECTOR_MODE © 
SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\SLINE 100 
L100: CLRL RO 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ This STEP command suspends program execution on line 99, just 
before a VVDIVD instruction is executed. Assume that, in this 
example, the instruction will trigger a floating-point divide-by-zero 
exception. 


@ This STEP command executes the VVDIVD instruction. Note, 
however, that the exception is not delivered at this point in the 
execution of the program. 


© The EXAMINE/FLOAT command displays a decoded exception 
message in element 1 of the destination register, V2 (see Section 11.7). 
This confirms that a floating-point divide-by-zero exception was 
triggered and is pending delivery. 


@ The SYNCHRONIZE VECTOR_MODE command forces the immediate 
delivery of the pending vector exception. (Note that you might obtain 
a different set of diagnostic messages if your program were using the 
VVIEF rather than vector processor hardware.) 


An alternative to using the SYNCHRONIZE VECTOR_MODE command is 
to operate the debugger in the synchronized vector mode by entering the 
command SET VECTOR_MODE SYNCHRONIZED. This command causes 
the debugger to force automatic synchronization between the scalar and 
vector processors whenever a vector instruction is executed. Specifically, 
the debugger issues a SYNC instruction after every vector instruction 
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and, in addition, an MSYNC instruction after any vector instruction that 
accesses memory. This forces the completion of all activities associated 
with the vector instruction that is being synchronized: 


e Any exception that was caused by a vector instruction is delivered 
before the next scalar instruction is executed. Note that forcing the 
delivery of a pending exception triggers an exception breakpoint or 
tracepoint (if one was set) or invokes an exception handler (if one is 
available at that location in the program). 


e Any read or write operation between vector registers and either 
the general registers or memory is completed before the next scalar 
instruction is executed. 


The following example shows the effect of the SET VECTOR_MODE 
SYNCHRONIZED command on the same instruction stream that was 
used in the previous example. Comments, keyed to the callouts, follow the 
example. 


DBG> SHOW VECTOR MODE 

Vector mode is nonsynchronized 

DBG> SET VECTOR MODE SYNCHRONIZED @ 
DBG> SHOW VECTOR MODE 

Vector mode is synchronized 


DBG> STEP 

stepped to .MAIN.\SUB\%LINE 99 
99: VVDIVD vVi1,V0,V2 

DBG> STEP 


SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%SLINE 100 
100? CLRL RO 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ The command SET VECTOR. MODE SYNCHRONIZED causes the 
debugger to force automatic synchronization between the scalar and 
vector processors whenever a vector instruction is executed. 


@ This STEP command suspends program execution on line 99, just 
before a VVDIVD instruction is executed. Assume that, as in the 
previous example, the instruction will trigger a floating-point divide- 
by-zero exception. 


© This STEP command executes the VVDIVD instruction, which triggers 
the exception. Note that the vector exception is delivered immediately 
because the debugger is being operated in synchronized vector mode. 


Note that, in addition to SYNCHRONIZE VECTOR_MODE and SET 
VECTOR_MODE SYNCHRONIZED, a few other debugger commands can 
affect synchronization—for example, SET WATCH. 
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11.9 Calling Routines That Might Affect the Program’s Vector State 


The CALL command’s /[NOJSAVE_VECTOR_STATE qualifiers enable you 
to control whether the current state of the vector processor is saved and 
then restored when a routine is called. 


The state of the VAX vector processor comprises the following: 
e The values of the vector registers and vector control registers 


e Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 


When you use the CALL command to execute a routine, execution of the 
routine might change the state of the vector processor as follows: 


e By changing the values of vector registers or vector control registers 
e By causing a vector exception 


e By causing the delivery of a vector exception that was pending when 
the CALL command was issued 


The command CALL/SAVE_VECTOR_STATE specifies that the state of 
the vector processor that exists before the CALL command is issued is 
restored by the debugger after the called routine has completed execution. 
This ensures that, after the called routine has completed execution: 


e Any vector exception that was pending delivery before the CALL 
command was issued is still pending delivery 


e¢ No vector exception that was triggered during the routine call is still 
pending delivery 


e The values of the vector registers are identical to their values before 
the CALL command was issued 


The command CALL/NOSAVE_VECTOR_STATE, which is the default, 
specifies that the state of the vector processor that exists before the CALL 
command is issued is not restored by the debugger after the called routine 
has completed execution. In this case, the state of the vector processor 
after the routine call depends on the effect (if any) of the called routine. 


The /[NOJSAVE_VECTOR_STATE qualifiers have no effect on the VAX 
general (scalar) registers. The values of these registers are always saved 
and restored when you execute a routine with the CALL command. 


11.10 Displaying Vector Register Data in Screen Mode 
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In screen mode, a register display shows the current values of the VAX 
general registers. (See Section 7.2.5.) 


To display data contained in vector registers or vector control registers in 
screen mode, use a DO display. (See Section 7.6.1.) 


Debugging Vectorized Programs 
11.10 Displaying Vector Register Data in Screen Mode 


For example, the following command creates a DO display named V2_DISP 
that shows the contents of elements 4 to 7 of register V2 (FORTRAN array 
syntax). The display is automatically updated whenever the debugger 
gains control from your program: 


DBG> DISPLAY VZ DISP AT RQ2Z DO (EXAMINE %V2(4:7)) 
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Debugger Command Dictionary 


1.1 


The Debugger Command Dictionary contains detailed reference 
information about all debugger commands, organized as follows: 


e Section 1 explains how to enter debugger commands. 


e Section 2 gives general information about debugger diagnostic 
messages. 


e Section 3 lists commands that apply only when you are using the 
debugger at a workstation running VWS (not DECwindows). 


e Section 4 contains detailed reference information about the debugger 
commands. 





Debugger Command Format 


General Format 


You can enter debugger commands interactively at the keyboard or store 
them within a command procedure to be invoked later with the @ (execute 
procedure) command. 


This section gives the following information: 
¢ General format for debugger commands 
¢ Rules for entering commands interactively at the keyboard 


e Rules for entering commands in debugger command procedures 


A command string is the complete specification of a debugger command. 
Although you can continue a command on more than one line, the term 
command string is used to define an entire command that is passed to the 
debugger. 


A debugger command string consists of a verb and, possibly, parameters 
and qualifiers. 


The verb specifies the command to be executed. Some debugger command 
strings might consist of only a verb or a verb pair. For example: 


DBG> GO 
DBG> SHOW IMAGE 


A parameter specifies what the verb acts on (for example, a file 
specification). A qualifier describes or modifies the action taken by the 
verb. Some command strings might include one or more parameters or 
qualifiers. In the following examples, COUNT, I, J, and K, OUT2, and 
PROG4.COM are parameters (@ is the "execute procedure" command); 
/SCROLL and /OUTPUT are qualifiers. 


DBG> SET WATCH COUNT 

DBG> EXAMINE I,J,K 

DBG> SELECT/SCROLL/OUTPUT OUT2 
DBG> @PROG4.COM 


Some commands accept optional WHEN or DO clauses. DO clauses are 
also used in some screen display definitions. 
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A WHEN clause consists of the keyword WHEN followed by a conditional 
expression (within parentheses) that evaluates to true or false in the 
current language. A DO clause consists of the keyword DO followed by 
one or more command strings (within parentheses) that are to be executed 
in the order that they are listed. You must separate multiple command 
strings with semicolons (;). These points are illustrated in the next 
example. 


The following command string sets a breakpoint on routine SWAP that is 
triggered whenever the value of J equals 4 during execution. When the 
breakpoint is triggered, the debugger executes the two command strings 
SHOW CALLS and EXAMINE I,K, in the order indicated. 


DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K) 


The debugger checks the syntax of the commands in a DO clause when it 
executes the DO clause. You can nest commands within DO clauses. 


1.2 Entering Commands at the Keyboard 
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When entering a debugger command interactively at the keyboard, you 
can abbreviate a keyword (verb, qualifier, parameter) to as few characters 
as are needed to make it unique within the set of all debugger keywords. 
However, some commonly used commands (for example, EXAMINE, 
DEPOSIT, GO, STEP) can be abbreviated to their first characters. Also, in 
some cases, the debugger interprets nonunique abbreviations correctly on 
the basis of context. 


Pressing the Return key terminates the current line, causing the debugger 
to process it. To continue a long command string on another line, type a 
hyphen (-) before pressing RETURN. As a result, the debugger prompt 

is prefixed with an underline character (_DBG>), indicating that the 
command string is still being accepted. 


You can enter more than one command string on one line by separating 
command strings with semicolons (;). 


To enter a comment (explanatory text that is recorded in a debugger log 
file but is otherwise ignored by the debugger), precede the comment text 
with an exclamation point (!). If the comment wraps to another line, start 
that line with an exclamation point. 


The command line editing functions that are available at the DCL prompt 
are also available at the debugger prompt, including command recall 
with the up arrow and down arrow keys. For example, pressing the left 
arrow and right arrow keys moves the cursor one character to the left and 
right, respectively; pressing CTRL/H and CTRL/E moves the cursor to the 
beginning and the end of the line, respectively; pressing CTRL/U deletes 
all the characters to the left of the cursor, and so on. 


To interrupt a command that is being processed by the debugger, press 
CTRL/C. (See the description of CTRL/C in the command dictionary.) 


1.3 Entering Commands in Command Procedures 


To maximize legibility, it is best not to abbreviate command keywords in 
a command procedure. Do not abbreviate command keywords to less than 
four significant characters (not counting the negation /NO ... ), to avoid 
potential conflicts in future releases. 


Start a debugger command line at the left margin. (Do not start a 
command line with a dollar sign ($) as you do when writing a DCL 
command procedure). 


The beginning of a new line ends the previous command line (the end- 
of-file character also ends the previous command line). To continue a 
command string on another line, type a hyphen (-) before starting the new 
line. 


You can enter more than one command string on one line by separating 
command strings with semicolons (;). 


To enter a comment (explanatory text that does not affect the execution of 
the command procedure), precede the comment text with an exclamation 
point (!). If the comment wraps to another line, start that line with an 
exclamation point. 





2 Debugger Diagnostic Messages 


The following example shows the elements of a debugger diagnostic 
message: 


SDEBUG-W-NOSYMBOL, symbol ’X’ is not in the symbol table 


@ The facility name (DEBUG). 
@ The severity level (W, in this example). 


© The message identifier (NOSYMBOL, in this example). The message 
identifier is an abbreviation of the message text. 


@ The message text. 
The identifier enables you to find the explanation for a diagnostic message 
from the debugger’s online help (and the action you need to take, if any). 


To obtain online help about a debugger message, use the following general 
command format: 


HELP MESSAGES message-identifier 
The possible severity levels for diagnostic messages are as follows: 


S (success) 

I (informational) 

W (warning) 

E (error) 

F (fatal, or severe error) 


Success and informational messages inform you that the debugger has 
performed your request. 
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Warning messages indicate that the debugger might have performed some, 
but not all, of your request and that you should verify the result. 


Error messages indicate that the debugger could not perform your request, 
but that the state of the debugging session was not changed. The only 
exceptions are if the message identifier was DBGERR or INTERR. These 
identifiers signify an internal debugger error, and you should submit a 
Software Performance Report (SPR) in such cases. 


Fatal messages indicate that the debugger could not perform your request 
and that the debugging session is in an indeterminate state from which 
you cannot recover reliably. Typically, the error ends the debugging 
session. 


3 Commands Recognized Only on Workstations Running VWS 


The following commands are recognized only when you are using the 
debugger at a workstation running VWS (not DECwindows): 


¢ SET MODE [NOJSEPARATE 
e SET PROMPT/[INOJPOP 


See the descriptions of these commands in the command dictionary in 


Section 4. All of the other debugger commands apply to workstations as 
well as terminals. 





4 Debugger Command Dictionary 
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The Debugger Command Dictionary describes each of the debugger 
commands in detail. Commands are listed alphabetically. The following 
information is provided for each command: command description, format, 
parameters, qualifiers, and one or more examples. See the preface of this 
manual for documentation conventions. 


@ (Execute Procedure) 


@ (Execute Procedure) 


Executes a debugger command procedure. 





FORMAT 


@ file-spec [parameter], ... ]] 





PARAMETERS 


file-spec 

Specifies the command procedure to be executed. For any part of the 
full file specification that is not provided, the debugger uses the file 
specification established with the last SET ATSIGN command, if any. If 
the missing part of the file specification was not established by a SET 
ATSIGN command, the debugger assumes SYS$DISK:[ ]JDEBUG.COM as 
the default file specification. You can specify a logical name. 


Par ameter 

Specifies a parameter that is passed to the command procedure. The 
parameter can be an address expression, a value expression in the current 
language, or a debugger command (the command must be enclosed within 
quotation marks (")). Note that, unlike with DCL, you must separate 
parameters by commas. Also, you can pass as many parameters as there 
are formal parameter declarations within the command procedure. For 


more information about passing parameters to command procedures, see 
the DECLARE command description. 





DESCRIPTION 


A debugger command procedure can contain any debugger commands, 
including another @ command. The debugger executes commands from the 
command procedure until it reaches an EXIT or QUIT command or the 
end of the file. At that point, the debugger returns control to the command 
stream that invoked the command procedure. A command stream can 

be the terminal, an outer (containing) command procedure, a DO clause 
in a command such as SET BREAK, or a DO clause in a screen display 
definition. 


By default, commands read from a command procedure are not echoed. If 
you enter the command SET OUTPUT VERIFY, all commands read from a 
command procedure are echoed on the current output device, as specified 
by DBG$OUTPUT (the default output device is SYS$OUTPUT). 


For information about passing parameters to command procedures, see the 
DECLARE command description. 


Related commands: (SET, SHOW) ATSIGN, SET OUTPUT [NO]VERIFY, 
SHOW OUTPUT, DECLARE. 
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@ (Execute Procedure) 





EXAMPLE 


DBG> SET ATSIGN USER: [JONES .DEBUG] .DBG 
DBG> SET OUTPUT VERIFY 
DBG> @CHECKOUT 
SDEBUG-I-VERIFYICF, entering command procedure CHECKOUT 
SET MODULE/ALL 
SET BREAK SUB1 
GO 
break at routine PROG5\SUB2 
EXAMINE X 
PROG5S\SUB2\X: 376 


S$DEBUG-I-VERIFYICF, exiting command procedure MAIN 
DBG> 


In this example, the command SET ATSIGN establishes that debugger 
command procedures are, by default, in USER:[JONES.DEBUG] and have 
a file type of DBG. The command @CHECKOUT executes the command 
procedure USER:[JONES.DEBUG]CHECKOUT.DBG. Commands 
contained within the command procedure are echoed because the command 
SET OUTPUT VERIFY was entered. 
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ATTACH 


ATTACH 


Passes control of your terminal from the current process to another process. 





FORMAT 


ATTACH  process-name 





PARAMETERS 


Pprocess-name 

Specifies the process to which your terminal is to be attached. The process 
must already exist before you try to attach to it. If the process name 
contains nonalphanumeric or space characters, you must enclose it in 
quotation marks ("). 





DESCRIPTION 


The ATTACH command allows you to go back and forth between a 
debugging session and your command interpreter, or between two 
debugging sessions. To do so, you must first use the SPAWN command 
to create a subprocess (see the description of the SPAWN command); 
you can then attach to it whenever you want. To return to your original 
process with minimal system overhead, use another ATTACH command. 


Related command: SPAWN. 





EXAMPLES 


DBG> SPAWN 


S ATTACH JONES 


%DEBUG-I-RETURNED, control returned to process JONES 
DBG> ATTACH JONES 1 


$ 


LO 


$ 


In this example, the series of commands creates a subprocess named 
JONES_1 from the debugger (currently running in the process JONES) 
and then attaches to that subprocess. 


DBG> ATTACH "Alpha One" 


This example illustrates use of quotation marks to enclose a process name 
that contains a space character. 
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CALL 


CALL 


Cails a routine that was linked with your program. 





FORMAT CALL routine-name [(argument[, ... ])] 


PARAMETERS routine-name 


Specifies the name or the memory address of the routine to be called. 


argument 

Specifies an argument that is required by the routine. Arguments can be 
passed by address (the default), by descriptor, by reference, and by value, 
as follows: 





%ADDR Passes the argument by address. This is the default. The format is as 
follows: 


CALL routine-name (%SADDR address-expression) 


The debugger evaluates the address expression and passes that address 
to the routine specified. For simple variables (such as X), the address of 
X is passed into the routine. This passing mechanism is how FORTRAN 
implements ROUTINE(X). In other words, for named variables, using 
%ADDR corresponds to a call by reference in FORTRAN. For other 
expressions, however, you must use the %REF function to call by 
reference. For complex or composite variables (such as arrays, records, 
and access types), the address is passed when you specify %ADDR, 
but the called routine might not handle the passed data properly. Do not 
specify a literal value (a number or an expression composed of numbers) 
when using %ADDR. 


%DESCR Passes the argument by descriptor. The format is as follows: 


CALL routine-name (%SDESCR language-expression) 


The debugger evaluates the language expression and builds a VAX- 
standard descriptor to describe the value. The descriptor is then passed 
to the routine you named. You would use this technique to pass strings 
to a FORTRAN routine. 


%REF Passes the argument by reference. The format is as follows: 


CALL routine-name (%SREF language-expression) 


The debugger evaluates the language expression and passes a pointer to 
the value, into the called routine. This passing mechanism corresponds 
to the way FORTRAN passes the result of an expression. 


%VAL Passes the argument by value. The format is as follows: 


CALL routine-name (%VAL language-expression) 


The debugger evaluates the language expression and passes the value 
directly to the called routine. 
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CALL 





QUALIFIERS 


/AST (default) 
/NOAST 


Controls whether the delivery of asynchronous system traps (ASTs) is 
enabled or disabled during the execution of the called routine. The 
/AST qualifier specifies that ASTs can be delivered, if delivery of ASTs 
was enabled before the CALL command was entered (that is, unless you 
previously entered the command DISABLE AST). The /NOAST qualifier 
specifies that ASTs cannot be delivered. 


/SAVE VECTOR STATE 
/NOSAVE_VECTOR_STATE (default) 
Note: This qualifier applies to vectorized programs. 


Controls whether the current state of the vector processor is saved and 
then restored when a routine is called with the CALL command. 


The state of the vector processor comprises the following: 


¢ The values of the vector registers (VO to V15) and the vector control 
registers (VCR, VLR, and VMR) 


e Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 


When you use the CALL command to execute a routine, execution of the 
routine might change the state of the vector processor as follows: 


¢ By changing the values of vector registers or vector control registers 
e By causing a vector exception 


e By causing the delivery of a vector exception that was pending when 
the CALL command was issued 


The /SAVE_VECTOR_STATE qualifier specifies that the state of the vector 
processor that exists before the CALL command is issued is restored by the 
debugger after the called routine has completed execution. This ensures 
that, after the called routine has completed execution: 


e Any vector exception that was pending delivery before the CALL 
command was issued is still pending delivery 


¢ No vector exception that was triggered during the routine call is still 
pending delivery 


e The values of the vector registers are identical to their values before 
the CALL command was issued 


The /NOSAVE_VECTOR_STATE qualifier, which is the default, specifies 
that the state of the vector processor that exists before the CALL command 
is issued is not restored by the debugger after the called routine has 
completed execution. In this case, the state of the vector processor after 
the routine call depends on the effect Gif any) of the called routine. 


The [NO]JSAVE_VECTOR_STATE qualifiers have no effect on the VAX 
general registers. The values of these registers are always saved and 
restored when you execute a routine with the CALL command. 
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CALL 





DESCRIPTION 
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The CALL command is one of the four debugger commands that can 

be used to execute your program (the others are GO, STEP, and EXIT). 
The command enables you to execute a routine independently of the 
normal execution of your program. The CALL command executes a routine 
whether or not your program actually includes a call to that routine, as 
long as the routine was linked with your program. 


When you enter a CALL command, the debugger takes the following 
action. (See the qualifier descriptions for additional information): 


1 Saves the current values of the VAX general registers. 
2 Constructs an argument list. 


3 Executes a call to the routine specified in the command and passes any 
arguments. 


4 Executes the routine. 


5 Displays the value returned by the routine in register RO. By VMS 
convention, after a called routine has executed, register RO contains 
the function return value (if the routine is a function) or the procedure 
completion status (if the routine is a procedure that returns a status 
value). If a called procedure does not return a status value or function 
value, the value in RO might be meaningless, and the "value returned" 
message can be ignored. 


6 Restores the values of the general registers to the values they had just 
before the CALL command was executed. 


7 Issues the prompt. 


The debugger assumes that the called routine conforms to the VMS 
procedure calling standard (see the VAX Architecture Handbook). However, 
note that the debugger does not know about all the argument-passing 
mechanisms for all supported languages. Therefore, you might need to 
specify how to pass parameters—for example, use CALL SUB1(%VAL 

X) rather than CALL SUBI1(X). See your language documentation for 
complete information about how arguments are passed to routines. 


Note that, if you use the CALL command to call a routine that modifies 
the value of a passed parameter and returns a new value, the returned 
value might be unreliable. 


A common debugging technique at an exception breakpoint (resulting from 
a SET BREAK/EXCEPTION or a STEP/EXCEPTION command) is to call 
a dump routine with the CALL command. When you enter the CALL 
command at an exception breakpoint, any breakpoints, tracepoints, or 
watchpoints that were previously set within the called routine are disabled 
temporarily so that the debugger does not lose the exception context. 
However, such eventpoints are active if you enter the CALL command at a 
location other than an exception breakpoint. 


When an exception breakpoint is triggered, execution is suspended before 
any application-declared condition handler is invoked. At an exception 
breakpoint, entering a GO or STEP command after executing a routine 
with the CALL command causes the debugger to resignal the exception 
(see the descriptions of the GO and STEP commands). 


CALL 


If you are using the multiprocess debugging configuration to debug a 
multiprocess program (if the logical name DBG$PROCESS has the value 
MULTIPROCESS), note the following additional points: 


e The CALL command is executed in the context of the visible process, 
but images in any other processes that are not on hold (through a SET 
PROCESS/HOLD command) are also allowed to execute. If you use the 
DO command to broadcast a CALL command to one or more processes, 
the CALL command is executed in the context of each specified process 
that is not on hold, but images in any other processes that are not on 
hold are also allowed to execute. In all cases, a hold condition in the 
visible process is ignored. 


e After execution is started, the way in which it continues depends on 
whether the command SET MODE [NOJINTERRUPT was entered. 
By default (SET MODE INTERRUPT), execution continues until it 
is suspended in any process. At that point, execution is interrupted 
in any other processes that were executing images, and the debugger 
prompts for input. 


Related commands: GO, STEP, EXIT, DO, SET PROCESS, SET MODE 
[NOJINTERRUPT, SET VECTOR_MODE [NOJSYNCHRONIZED, 
SYNCHRONIZE VECTOR_MODE. 





EXAMPLES 


DBG> CALL SUB1 (X) 
value returned is 19 
DBG> 


This command calls the routine SUBI, passing the address of X as the 
required parameter (by default, the address of the argument specified is 
passed). The routine is a function whose returned value is 19. 


DBG> CALL SUB(%SREF 1) 
value returned is 1 
DBG> 


This command passes a pointer to a memory location containing the 
- numeric literal 1, into the routine SUB. 


DBG> SET MODULE SHARESLIBRTL 

DBG> CALL LIBSSHOW_VM 
1785 calls to LIBSGET_VM, 284 calls to LIBSFREE VM, 122216 bytes 
still allocated, value returned is 00000001 

DBG> 


This example shows how you could call the run-time library routine 
LIB$SHOW_VM (in the shareable image LIBRTL) to display memory 
statistics. The SET MODULE command makes the universal symbols 
(routine names) in LIBRTL visible in the main image. See the description 
of the /SHARE qualifier of the SHOW MODULE command for more 
information about this subject. 
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CALL 


4 SUBROUTINE CHECK TEMP (TEMPERATURE, ERROR_MESSAGE) 
REAL TOLERANCE /4.7/ 
REAL TARGET TEMP /92.0/ 
CHARACTER* (*) ERROR_MESSAGE 


IF (TEMPERATURE .GT. (TARGET TEMP + TOLERANCE) ) THEN 
TYPE *,’Input temperature out of range:’ , TEMPERATURE 
TYPE *,EBRROR_ MESSAGE 

ELSE 


TYPE *,’Input temperature in range:’ , TEMPERATURE 
END IF 
RETURN 
END 


DBG> CALL CHECK TEMP (REF 100.0, %SDESCR ’TOLERANCE-CHECK 1 FAILED’ ) 
Input temperature out of range: 100.0000 

TOLERANCE-CHECK 1 FAILED 

value returned is 0 

DBG> CALL CHECK TEMP (SREF 95.2, *DESCR ’TOLERANCE-CHECK 2 FATLED’ ) 
Input temperature in range: 95.2000 

value returned is 0 

DBG> 


In this example, the source code is that of a FORTRAN routine (CHECK_ 
TEMP) that accepts two parameters, TEMPERATURE (a real number) and 
ERROR_MESSAGE (a string). Depending on the value of the temperature, 
the routine prints different output. Each of the two CALL commands 
passes a temperature value (by reference) and an error message (by 
descriptor). Because this routine does not have a formal return value, 

the value returned is undefined, in this case, 0. 
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CANCEL ALL 


CANCEL ALL 


Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope 
and type to their default values. Restores the line, symbolic, and G_Float 
modes established with the SET MODE command to their default values. 





FORMAT CANCEL ALL 





QUALIFIERS /PREDEFINED 


Cancels all predefined (but no user defined) breakpoints, tracepoints, and 
watchpoints. 


/USER 

Cancels all user defined (but no predefined) breakpoints, tracepoints, 
and watchpoints. CANCEL ALL/USER is assumed by default unless you 
specify /PREDEFINED. 





DESCRIPTION The CANCEL ALL command performs the followings steps: 


¢ Cancels all breakpoints, tracepoints, and watchpoints. This is 
equivalent to entering the commands CANCEL BREAK/ALL, CANCEL 
TRACE/ALL, and CANCEL WATCH/ALL. Depending on the type 
of program (for example Ada, multiprocess), certain predefined 
breakpoints or tracepoints might be set automatically when you invoke 
the debugger. By default (CANCEL ALL/USER), only user defined 
breakpoints, tracepoints, and watchpoints are canceled—those that 
were previously set explicitly with the SET BREAK, SET TRACE, 
and SET WATCH commands. If you specify /PREDEFINED but not 
/USER, all predefined (but no user defined) breakpoints, tracepoints, 
and watchpoints are canceled. If you specify both /PREDEFINED and 
/USER, all predefined and user defined breakpoints, tracepoints, and 
watchpoints are canceled. 


See Section 9.3.2 for information about predefined breakpoints 
associated with Ada tasking exception events. See Chapter 10 for 
information about predefined tracepoints associated with multiprocess 
programs. 


¢ Restores the scope search list to its default value (0,1,2,... ,n). This 
is equivalent to entering the CANCEL SCOPE command. 


e Restores the data type for memory locations that are associated with 
a compiler generated type to the associated type. Restores the type 
for locations that are not associated with a compiler generated type 
to "longword integer". This is equivalent to entering the commands 
CANCEL TYPE/OVERRIDE and SET TYPE LONGWORD. 
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CANCEL ALL 





EXAMPLES 


DBG> CANCEL ALL 


DBG> CANCEL ALL 


¢ Restores the line, symbolic, and G_Float modes established with the 
SET MODE command to their default values. This is equivalent to 
entering the following command: 


DBG> SET MODE LINE, SYMBOLIC,NOG FLOAT 


The CANCEL ALL command does not affect the current language setting 
or modules included in the run-time symbol table. 


Related commands: CANCEL BREAK, CANCEL TRACE, CANCEL 
WATCH, CANCEL SCOPE, CANCEL TYPE/OVERRIDE, SET TYPE, 
(SET, CANCEL) MODE. | 


This command cancels all user defined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. In this example, there are no predefined breakpoints, tracepoints, 
or watchpoints. 


SDEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled 


DBG> 


This command cancels all user defined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their 
default values. In this example, there are some predefined breakpoints, 
tracepoints, or watchpoints, and these are not canceled by default. 


DBG> CANCEL ALL/PREDEFINED 
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This command cancels all predefined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. No user defined breakpoints, tracepoints, or watchpoints are 
affected. 


CANCEL BREAK 


CANCEL BREAK 


Cancels a breakpoint. 











FORMAT CANCEL BREAK [address-expressionf, ... ]] 
PARAMETERS address-expression 
Specifies a breakpoint to be canceled. Do not use the asterisk wildcard 
character (*). Do not specify an address expression when using any of the 
qualifiers except for /EVENT, /PREDEFINED, or /USER. 
QUALIFIERS /ACTIVATING 


Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


Cancels the effect of a previous SET BREAK/ACTIVATING command. Do 
not specify an address expression with /ACTIVATING. 


/ALL 

By default, cancels all user defined breakpoints. When used with 
/PREDEFINED, cancels all predefined breakpoints but no user defined 
breakpoints. Specify both /USER and /PREDEFINED to cancel all 
breakpoints. Do not specify an address expression with /ALL. 


/BRANCH 
Cancels the effect of a previous SET BREAK/BRANCH command. Do not 
specify an address expression with /BRANCH. 


/CALL 
Cancels the effect of a previous SET BREAK/CALL command. Do not 
specify an address expression with /CALL. 


/EVENT=event-name 
Note: This qualifier applies to Ada and SCAN programs. See the 
VAX Ada and VAX SCAN documentation for complete information. 


Cancels the effect of a previous SET BREAK/EVENT=event-name 
command. Specify the event name (and address expression, if any) exactly 
as they were specified with the SET BREAK/EVENT command. Event 
names depend on the run-time facility and are identified in Appendix E 
for Ada and SCAN. You can display the event names associated with 

the current run-time facility by entering the SHOW EVENT_FACILITY 
command. 


/EXCEPTION 
Cancels the effect of a previous SET BREAK/EXCEPTION command. Do 
not specify an address expression with /EXCEPTION. 
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CANCEL BREAK 


ANSTRUCTION 
Cancels the effect of a previous SET BREAK/INSTRUCTION command. 
Do not specify an address expression with /INSTRUCTION. 


/LINE 
Cancels the effect of a previous SET BREAK/LINE command. Do not 
specify an address expression with /LINE. 


/PREDEFINED 


Cancels a specified predefined breakpoint without affecting any user 
defined breakpoints. When used with /ALL, cancels all predefined 
breakpoints. 


/TERMINATING 


Cancels the effect of a previous SET BREAK/TERMINATING command. 
Do not specify an address expression with /TERMINATING. 


/USER 

Cancels a specified user defined breakpoint without affecting any 
predefined breakpoints. When used with /ALL, cancels all user defined 
breakpoints. CANCEL BREAK/USER is assumed by default unless you 
specify /(PREDEFINED. 


/VECTOR_INSTRUCTION 
Note: This qualifier applies to vectorized programs. 


Cancels the effect of a previous SET BREAK/VECTOR_INSTRUCTION 
command. Do not specify an address expression with 
/VECTOR_INSTRUCTION. 





DESCRIPTION 
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Breakpoints can be user defined or predefined. User defined breakpoints 
are those that you set explicitly with the SET BREAK command. 
Predefined breakpoints, which depend on the type of program you 

are debugging (for example, Ada or multiprocess), are established 
automatically when you invoke the debugger. Use the SHOW BREAK 
command to identify all breakpoints that are currently set. Any predefined 
breakpoints are identified as such. 


User defined and predefined breakpoints are set and canceled 
independently. For example, a location or event can have both a 
user defined and a predefined breakpoint. Canceling the user defined 
breakpoint does not affect the predefined breakpoint, and conversely. 


To cancel only user defined breakpoints, do not specify /PREDEFINED 
with the CANCEL BREAK command (/USER is the default). To cancel 
only predefined breakpoints, specify /PREDEFINED but not /USER. To 
cancel both user defined and predefined breakpoints, specify both /USER 
and /PREDEFINED. 


In general, note that the effect of the CANCEL BREAK command is 
symmetrical with that of the SET BREAK command (even though the SET 
BREAK command is used only with user defined breakpoints). Thus, to 
cancel a breakpoint that was established at a specific location, specify that 
same location (address expression) with the CANCEL BREAK command. 
To cancel breakpoints that were established on a class of instructions or 


CANCEL BREAK 


events, specify the class of instructions or events with the corresponding 
qualifier (for example, /LINE, /BRANCH, /ACTIVATING, /EVENT=, and so 
on). See the qualifier descriptions for more specific information. 


Related commands: (SET, SHOW) BREAK, (SET, SHOW, CANCEL) 
TRACE, CANCEL ALL, (SET, SHOW) EVENT_FACILITY. 





EXAMPLES 


DBG> CANCEL BREAK MAIN\LOOP+10 


This command cancels the user defined breakpoint set at the address 
expression MAIN \ LOOP+10. 


DBG> CANCEL BREAK/ALL 

This command cancels all user defined breakpoints. 
DBG> CANCEL BREAK/ALL/USER/PREDEFINED 

This command cancels all user defined and predefined breakpoints. 
DBG_1> CANCEL BREAK/ACTIVATING 


This command cancels a previous user defined SET BREAK/ACTIVATING 
command. As a result, the debugger does not suspend execution when a 
new process is brought under debugger control. 


DBG> CANCEL BREAK/EVENT=DEPENDENTS EXCEPTION/PREDEFINED 


This command cancels the predefined breakpoint set on dependent 
exceptions. This breakpoint is predefined for Ada programs. 
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CANCEL DISPLAY 


CANCEL DISPLAY 


Permanently deletes a screen display. 





FORMAT 


CANCEL DISPLAY ([disp-namef, ... |] 





PARAMETERS 


disp-name 

Specifies the name of a display to be canceled. Do not specify the PROMPT 
display, which cannot be canceled. Do not use the asterisk wildcard 
character (*). Do not specify a display name with /ALL. 





QUALIFIERS 


/ALL 


Cancels all displays, except for the PROMPT display. Do not specify a 
display name with /ALL. 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 





DESCRIPTION 
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When a display is canceled, its contents are permanently lost, it is deleted 
from the display list, and all the memory that was allocated to it is 
released. 


You cannot cancel the PROMPT display. 


Related commands: (SET, SHOW) DISPLAY, (SET, SHOW, CANCEL) 
WINDOW. 


CANCEL DISPLAY 





EXAMPLE 


DBG> CANCEL DISPLAY SRC2 


This command permanently deletes display SRC2. 


DBG> CANCEL DISPLAY/ALL 


This command permanently deletes all displays, except for the PROMPT 
display. 
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CANCEL IMAGE 


CANCEL IMAGE 


Deletes symbol table information for a shareable image. 





FORMAT CANCELIMAGE /[/image-name[, ... |] 





PARAMETERS image-name 


Specifies a previously set shareable image to be canceled. Do not specify 
the main image, which cannot be canceled. Do not use the asterisk 
wildcard character (*). Do not specify an image name with /ALL. 





QUALIFIERS /ALL 


Specifies that all shareable images except the main image are to be 
canceled. Do not specify an image name with /ALL. 





DESCRIPTION The CANCEL IMAGE command deallocates the data structures previously 
built to debug a shareable image by a SET IMAGE command. Use the 
CANCEL IMAGE command if the debugger performance has slowed down 
because of many images and modules being set. You can also use the 
CANCEL MODULE command to delete only certain modules from an 
image’s run-time symbol table (RST) without canceling the entire image. 
Also, if dynamic mode is enabled (this is the default), you can disable it 
with the command SET MODE NODYNAMIC. As a result, the debugger 
does not set images or modules automatically. 


If the current image (the image last set with the SET IMAGE command) 
is canceled, the main image (the image containing the image transfer 
address) becomes the current image. 


Related commands: (SET, SHOW) IMAGE, (SET, SHOW, CANCEL) 
MODULE, SET MODE [NO]JDYNAMIC. 





EXAMPLE 


DBG> CANCEL IMAGE SHARE2, SHARE3 


This command cancels shareable images SHARE2 and SHARES. If either 
of these was the current image, the main image becomes the current 
image. 
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CANCEL MODE 


CANCEL MODE 


Restores the line, symbolic, and G_float modes established by the SET 
MODE command to their default values. Also restores the default input/output 
radix. 





FORMAT CANCEL MODE 





DESCRIPTION The effect of the CANCEL MODE command is equivalent to entering the 
following commands: 


DBG> SET MODE LINE, SYMBOLIC,NOG FLOAT 
DBG> CANCEL RADIX 


Note that, although the same default modes apply to all languages, the 
default radix for both data entry and display is decimal for all languages 
except BLISS and MACRO. It is hexadecimal for BLISS and MACRO. 


Related commands: (SET, SHOW) MODE, (SET, SHOW, CANCEL) 
RADIX. 





EXAMPLE 


DBG> CANCEL MODE 


This command restores the default radix mode and all default mode 
values. 
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CANCEL MODULE 


CANCEL MODULE 


Deletes the symbol records of a module in the current image from the run-time 
symbol table (RST) for that image. 





FORMAT 


CANCEL MODULE /[module-namef, ... ]] 





PARAMETERS 


module-name 

Specifies the name of a module whose symbol records are deleted from 
the RST. Do not use the asterisk wildcard character (*). Do not specify a 
module name with /ALL. 





QUALIFIERS 


/ALL 


Deletes the symbol records of all modules from the RST. Do not specify a 
module name or /[NOJRELATED with /ALL. 


/RELATED (default) 


/NORELATED 
Note: This qualifier applies to Ada programs. 


Controls whether the debugger deletes from the RST the symbol records 
of a module that is related to a specified module through a with-clause or 
subunit relationship. 


CANCEL MODULE/RELATED deletes symbol records for related modules 
as well as for those specified, but not for any module that is also related 
to another set module. The effect of CANCEL MODULE/RELATED is 
consistent with Ada’s scope and visibility rules and depends on the actual 
relationship between modules. CANCEL MODULE/NORELATED deletes 
symbol records only for modules that are specified (no symbol records are 
deleted for related modules). 





DESCRIPTION 
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Note: The current image is either the main image (by default) 
or the image established as the current image by a previous SET 
IMAGE command. 


Use the CANCEL MODULE command if the debugger performance has 
slowed down because of many modules being set. You can also use the 
CANCEL IMAGE command to delete the symbols of an entire image (this 
automatically cancels all of the modules in that image). Also, if dynamic 
mode is enabled (this is the default), you can disable it with the command 
SET MODE NODYNAMIC. As a result, the debugger does not set modules 
or images automatically. 


The CANCEL MODULE command does not cancel any breakpoints, 
tracepoints, or watchpoints that are set currently. It deletes the 
symbolization of any breakpoints, tracepoints, or watchpoints associated 
with the canceled modules. 


CANCEL MODULE 


Related commands: (SET, SHOW) MODULE, SET MODE [NO]JDYNAMIC, 
(SET, SHOW, CANCEL) IMAGE. 





EXAMPLES 


DBG> CANCEL MODULE SUB1 


This command deletes the symbols of module SUB1 from the RST. 
DBG> CANCEL MODULE/ALL 


This command deletes the symbols of all modules from the RST. 
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CANCEL RADIX 


CANCEL RADIX 


Restores the default radix for the entry and display of integer data. 





FORMAT 


CANCEL RADIX 





QUALIFIERS 


/OVERRIDE 

Cancels the override radix established by a previous SET RADIX 
/OVERRIDE command. This sets the current override radix to "none" and 
restores the output radix mode to the value established with a previous 
SET RADIX or SET RADIX/OUTPUT command. If you did not change 
the radix mode with a SET RADIX or SET RADIX/OUTPUT command, 
the CANCEL RADIX/OVERRIDE command restores the radix mode to 

its default value (decimal for all languages except BLISS and MACRO, 
hexadecimal for BLISS and MACRO). 





DESCRIPTION 


The CANCEL RADIX command cancels the effect of any previous SET 
RADIX and SET RADIX/OVERRIDE commands. It restores the input and 
output radix to their default value (decimal for all languages except BLISS 
and MACRO, hexadecimal for BLISS and MACRO). 


The effect of the CANCEL RADIX/OVERRIDE command is more limited 
and is explained in the description of the /OVERRIDE qualifier. 


Related commands: (SET, SHOW) RADIX, EVALUATE. 





EXAMPLES 


DBG> CANCEL RADIX 


This command restores the default input and output radix. 


DBG> CANCEL RADIX/OVERRIDE 
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This command cancels any override radix you might have set with the 
SET RADIX/OVERRIDE command. 


CANCEL SCOPE 


CANCEL SCOPE 


Restores the default scope search list for symbol lookup. 





FORMAT 


CANCEL SCOP 





DESCRIPTION 


The CANCEL SCOPE command cancels the current scope search list 
established by a previous SET SCOPE command and restores the default 
scope search list, namely 0,1,2, ... ,n, where n is the number of calls in 
the call stack. 


The default scope search list specifies that, for a symbol without a path 
name prefix, a symbol lookup such as "EXAMINE X" first looks for X in 
the routine that is currently executing (scope 0); if no X is visible there, 
the debugger looks in the caller of that routine (scope 1), and so on down 
the call stack; if X is not found in scope n, the debugger searches the rest 
of the run-time symbol table (RST), then searches the global symbol table 
(GST), if necessary. 


Related commands: (SET, SHOW) SCOPE. 





EXAMPLE 


DBG> CANCEL SCOPE 


This command cancels the current scope. 
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CANCEL SOURCE 


CANCEL SOURCE 


Cancels a source directory search list established by a previous SET 
SOURCE command. 





FORMAT 


CANCEL SOURCE 





QUALIFIERS 


/EDIT 
Note: This qualifier applies mainly to Ada programs. 


Cancels the effect of a previous SET SOURCE/EDIT command. As a 
result, when you use the EDIT command, the debugger searches for a 
source file in the same directory that it was in at compile time. The 
CANCEL SOURCE/EDIT command does not cancel the effect of a previous 
SET SOURCE command. 


/MODULE=module-name 


Cancels the effect of a previous SET SOURCE/MODULE=module-name 
command in which the same module name was specified. (module-name 
specifies a module for which a source directory search list is canceled). As 
a result, the debugger searches for the source file of the specified module in 
the same directory that it was in at compile time. The CANCEL SOURCE 
/MODULE=module-name command does not cancel the effect of a previous 
SET SOURCE command, or of a SET SOURCE/MODULE=module-name 
command in which a different module name was specified. 





DESCRIPTION 
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When used without a qualifier, the CANCEL SOURCE command cancels 
the effect of a previous SET SOURCE command used without a qualifier. 
CANCEL SOURCE does not cancel the effect of a previous SET SOURCE 
/EDIT or SET SOURCE/MODULE=module-name commands. 


See the qualifier descriptions for an explanation of their effects. 


The /EDIT qualifier is needed when the files used for the display of source 
code are different from the files to be edited by means of the EDIT 
command. This is the case with Ada programs. For Ada programs, the 
(SET, SHOW, CANCEL) SOURCE commands affect the search of files used 
for source display (the "copied" source files in Ada program libraries); 
the (SET, SHOW, CANCEL) SOURCE/EDIT commands affect the search 
of the source files that you edit when using the EDIT command. If you 
use /MODULE with /EDIT, the effect of /EDIT is further qualified by 
/MODULE. 


Related commands: (SET, SHOW) SOURCH, (SET, SHOW) MAX_ 
SOURCE_FILES. 


CANCEL SOURCE 





EXAMPLE 


DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 
[] 
SYSTEM: : DEVICE: [PROJD] 

source directory search list for all other modules: 
[PROJA] 
[PROJB] 
[PETER.PROJC] 

DBG> CANCEL SOURCE 

DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 
[] 
SYSTEM: :DEVICE: [PROJD] 

DBG> CANCEL SOURCE/MODULE=COBOLTEST 

DBG> SHOW SOURCE 

no directory search list in effect 

DBG> 


In this example, the CANCEL SOURCE command cancels the effect of a 
previous SET SOURCE command. It does not cancel any source directory 
search lists for specific modules. But the command CANCEL SOURCE 
/MODULE=module-name (in this case, COBOLTEST) cancels the source 
directory search list for that module. 
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CANCEL TRACE 


CANCEL TRACE 


Cancels a tracepoint. 





FORMAT CANCEL TRACE /address-expressionf, ... ]] 





PARAMETERS address-expression 


Specifies a tracepoint to be canceled. Do not use the asterisk wildcard 
character (*). Do not specify an address expression when using any of the 
qualifiers except for /EVENT, /PREDEFINED, or /USER. 





QUALIFIERS /ACTIVATING 


Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


Cancels the effect of a previous SET TRACE/ACTIVATING command. Do 
not specify an address expression with /ACTIVATING. 


/ALL 


By default, cancels all user defined tracepoints. When used with 
/PREDEFINED, cancels all predefined tracepoints but no user defined 
tracepoints. Specify both /USER and /PREDEFINED to cancel all 
tracepoints. Do not specify an address expression with /ALL. 


/BRANCH 
Cancels the effect of a previous SET TRACE/BRANCH command. Do not 
specify an address expression with /BRANCH. 


/CALL 


Cancels the effect of a previous SET TRACE/CALL command. Do not 
specify an address expression with /CALL. 


/EVENT=event-name 
Note: This qualifier applies to Ada and SCAN programs. See the 
VAX Ada and VAX SCAN documentation for complete information. 


Cancels the effect of a previous SET TRACE/EVENT=event-name 
command. Specify the event name (and address expression, if any) exactly 
as they were specified with the SET TRACE/EVENT command. Event 
names depend on the run-time facility and are identified in Appendix E 
for Ada and SCAN. You can display the event names associated with 

the current run-time facility by entering the SHOW EVENT_FACILITY 
command. 


/EXCEPTION 
Cancels the effect of a previous SET TRACE/EXCEPTION command. Do 
not specify an address expression with /EXCEPTION. 
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CANCEL TRACE 


ANSTRUCTION 


Cancels the effect of a previous SET TRACE/AINSTRUCTION command. 
Do not specify an address expression with /INSTRUCTION. 


/LINE 
Cancels the effect of a previous SET TRACE/LINE command. Do not 
specify an address expression with /LINE. 


/PREDEFINED 


Cancels a specified predefined tracepoint without affecting any user 
defined tracepoints. When used with /ALL, cancels all predefined 
tracepoints. 


/TERMINATING 


Cancels the effect of a previous SET TRACE/TERMINATING command. 
Do not specify an address expression with /TERMINATING. 


/USER 


Cancels a specified user defined tracepoint without affecting any 
predefined tracepoints. When used with /ALL, cancels all user defined 
tracepoints. CANCEL BREAK/USER is assumed by default unless you 
specify /PREDEFINED. 


/VECTOR_INSTRUCTION 
Note: This qualifier applies to vectorized programs. 


Cancels the effect of a previous SET TRACE/VECTOR_INSTRUCTION 
command. Do not specify an address expression with /VECTOR_ 
INSTRUCTION. 





DESCRIPTION 


Tracepoints can be user defined or predefined. User defined tracepoints are 
those that you set explicitly with the SET TRACE command. Predefined 
tracepoints, which depend on the type of program you are debugging 

(for example, Ada or multiprocess), are established automatically when 
you invoke the debugger. Use the SHOW TRACE command to identify 

all tracepoints that are currently set. Any predefined tracepoints are 
identified as such. 


User defined and predefined tracepoints are set and canceled 
independently. For example, a location or event can have both a user 
defined and a predefined tracepoint. Canceling the user defined tracepoint 
does not affect the predefined tracepoint, and conversely. 


To cancel only user defined tracepoints, do not specify /PREDEFINED with 
the CANCEL TRACE command (/USER is the default). To cancel only 
predefined tracepoints, specify /PREDEFINED but not /USER. To cancel 
both user defined and predefined tracepoints, specify both /USER and 
/PREDEFINED. 


In general, note that the effect of the CANCEL TRACE command is 
symmetrical with that of the SET TRACE command (even though the SET 
TRACE command is used only with user defined tracepoints). Thus, to 
cancel a tracepoint that was established at a specific location, specify that 
same location (address expression) with the CANCEL TRACE command. 
To cancel tracepoints that were established on a class of instructions or 
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CANCEL TRACE 


events, specify the class of instructions or events with the corresponding 
qualifier (for example, /LINE, /BRANCH, /ACTIVATING, /EVENT=, and so 
on). See the qualifier descriptions for more specific information. 


Related commands: (SET, SHOW) TRACH, (SET, SHOW, CANCEL) 
BREAK, CANCEL ALL, (SET, SHOW) EVENT_FACILITY. 





EXAMPLES 
DBG> CANCEL TRACE MAIN\LOOP+10 


This command cancels the user defined tracepoint at the location 
MAIN\ LOOP+10. 


DBG> CANCEL TRACE/ALL 


This command cancels all user defined tracepoints. 


DBG_1> CANCEL TRACE/TERMINATING 


This command cancels a previous user defined SET TRACE 
/TERMINATING command. As a result, a tracepoint is not triggered 
when a process performs an image exit. 
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CANCEL TYPE/OVERRIDE 


CANCEL TYPE/OVERRIDE 


Cancels the override type established by a previous SET TYPE/OVERRIDE 
command. 





FORMAT CANCEL TYPE/OVERRIDE 





QUALIFIERS /OVERRIDE 


This qualifier must be specified. 





DESCRIPTION = The CANCEL TYPE/OVERRIDE command sets the current override type 
to "none". As a result, a program location associated with a compiler 
generated type is interpreted according to that type. 


Related commands: (SET, SHOW) TYPE/OVERRIDE, EXAMINE, 
DEPOSIT. 





EXAMPLE 


DBG> CANCEL TYPE/OVERRIDE 


This command cancels the effect of a previous SET TYPE/OVERRIDE 
command. 
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CANCEL WATCH 


CANCEL WATCH 


Cancels a watchpoint. 





FORMAT CANCEL WATCH /address-expressionf, ... |] 





PARAMETERS address-expression 


Specifies a watchpoint to be canceled. With high-level languages, this 
is typically the name of a variable. Do not use the asterisk wildcard 
character (*). Do not specify an address expression with /ALL. 





QUALIFIERS /ALL 


Cancels all watchpoints. Do not specify an address expression with /ALL. 





DESCRIPTION The effect of the CANCEL WATCH command is symmetrical with the 
effect of the SET WATCH command. To cancel a watchpoint that was 
established at a specific location with the SET WATCH command, specify 
that same location with the CANCEL WATCH command. Thus, to cancel 
a watchpoint that was set on an entire aggregate, specify the aggregate in 
the CANCEL WATCH command; to cancel a watchpoint that was set on 
one element of an aggregate, specify that element in the CANCEL WATCH 
command. 


Note that the CANCEL ALL command also cancels all watchpoints. 


Related commands: (SET, SHOW) WATCH, (SET, SHOW, CANCEL) 
BREAK, (SET, SHOW, CANCEL) TRACE, CANCEL ALL. 





EXAMPLES 


DBG> CANCEL WATCH SUB2\TOTAL 


This command cancels the watchpoint at variable TOTAL in module SUB2. 


DBG> CANCEL WATCH/ALL 


This command cancels all watchpoints you have set. 
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CANCEL WINDOW 


CANCEL WINDOW 


Permanently deletes a screen window definition. 





FORMAT CANCEL WINDOW [wnamef,... J] 





PARAMETERS Whame 


Specifies the name of a screen window definition to be canceled. Do not 
use the asterisk wildcard character (*). Do not specify a window definition 
name with /ALL. 





QUALIFIERS /ALL 


Cancels all predefined and user-defined window definitions. Do not specify 
a window definition name with /ALL. 





DESCRIPTION When a window definition is canceled, you can no longer use its name in a 
DISPLAY command. The command does not affect any displays. 


Related commands: (SET, SHOW) WINDOW, (SET, SHOW, CANCEL) 
DISPLAY. 





EXAMPLE 


DBG> CANCEL WINDOW MIDDLE 


This command permanently deletes the screen window definition 
MIDDLE. 
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CONNECT 


CONNECT 


Note: This command applies only to a multiprocess debugging 
configuration (when DBG$PROCESS has the value MULTIPROCESS). 


Interrupts an image that is running without debugger control in another 
process and brings that process under debugger control. When used without 
a parameter, brings any spawned process that is waiting to connect to the 
debugger under debugger control. 











FORMAT CONNECT  /[process-specf, ... |] 
PARAMETERS rocess-spec | a 
Specifies a process in which an image to be interrupted is running. The 
process must be in the same VMS job as the process in which the debugger 
was invoked. Use any of the following forms: 
[%PROCESS_ NAME] process-name The VMS process name, if that name 
contains no space or lowercase characters. 
The process name can include the asterisk 
wildcard character (*). 
[%PROCESS_NAME]} "process- The VMS process name, if that name 
name" contains space or lowercase characters. 
You can also use apostrophes (’ ) instead of 
quotation marks ("). 
%PROCESS_PID process_id The VMS process identification number (PID, 
a hexadecimal number). 
DESCRIPTION When you specify a process, the CONNECT command enables you to 
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interrupt an image that is running without debugger control in that 
process and bring the process under debugger control. The command is 
useful if, for example, you run a debuggable image with the DCL command 
RUN/NODEBUG or if your program issues a LIB$SPAWN run-time library 
call or a $CREPRC system service call that does not invoke the debugger. 


You can bring a process under debugger control in this manner only if that 
process is in the same VMS job as the process in which the debugger was 
invoked, and only if the image was not linked with the /NOTRACEBACK 
command qualifier. Also, you have full symbolic information for that image 
only if its modules were compiled and linked with the /DEBUG command 
qualifier. 


When the process is brought under debugger control, execution of the 
image is suspended at the point at which it was interrupted. 


When you do not specify a process, the CONNECT command brings any 
processes that are waiting to connect to your debugging session under 
debugger control. If no process is waiting, you can press CTRL/C to abort 
the CONNECT command. 


CONNECT 


By default, a tracepoint is triggered when a process is brought under 
debugger control. This predefined tracepoint is equivalent to that resulting 
from entering the command SET TRACE/ACTIVATING. The process is 


then known to the debugger and can be identified in a SHOW PROCESS 
display. 


Related commands: CTRL/Y, (SET,SHOW,CANCEL) TRACE. 





EXAMPLES 


DBG_1> CONNECT 


This command brings any processes that are waiting to be connected to 
the debugger under debugger control. 


DBG_1> CONNECT JONES 3 


This command interrupts the image running in process JONES_3 and 
brings the process under debugger control. Process JONES_3 must be 
in the same VMS job as the process in which the debugger was invoked. 
Also, the image must not have been linked with the /NOTRACEBACK 
qualifier. 
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CTRL/C 


CTRL/C 


When entered from within a debugging session, aborts the execution of a 
debugger command or interrupts program execution without interrupting the 
debugging session. 


Note: Do not use CTRL/Y from within a debugging session. 








FORMAT 
DESCRIPTION Pressing CTRL/C enables you to abort the execution of a debugger 
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command or to interrupt program execution without interrupting the 
debugging session. This is useful when, for example, the program is 
executing an infinite loop that does not have a breakpoint, or you want 
to abort a debugger command that takes a long time to complete. The 
debugger prompt is then displayed, so that you can enter debugger 
commands. 


After a CTRL/C interruption, any processes of a multiprocess program that 
were executing images are in the "interrupted" state. 


If your program already has a CTRL/C AST service routine enabled, use 
the SET ABORT_KEY command to assign the debugger’s abort function 
to another CTRL—key sequence. Note, however, that many CTRL—key 
sequences have VMS predefined functions, and the SET ABORT_KEY 
command enables you to override such definitions (see the VM@S DCL 
Concepts Manual). Some of the CTRL—key characters not used by the 
VMS operating system are G, K, N, and P. 


If your program does not have a CTRL/C AST service routine enabled, and 
you assign the debugger’s abort function to another CTRL—key sequence, 

the CTRL/C sequence then behaves like CTRL/Y—that is, it interrupts the 
debugging session and returns you to DCL level. 


Do not use CTRL/Y from within a debugging session. Always use either 
CTRL/C or an equivalent CTRL—key sequence established with the SET 
ABORT_KEY command. 


Note that you can use the SPAWN and ATTACH commands to leave and 
return to a debugging session without losing the debugging context. 


Related commands: SET ABORT_KEY, SPAWN, ATTACH, CTRL/Y. 


CTRL/C 





EXAMPLE 


DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 
1000: 
1004: 
1008: 
1012: 
1016: 
SDEBUG-W-ABORTED, command aborted by user request 
DBG> 


OOO 0 © 


This example shows how to use the CTRL/C sequence to, first, interrupt 
program execution, and then, abort the execution of a debugger command. 
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CTRL/W, CTRL/Z 


CTRL/W, CTRL/Z 


CTRL/W refreshes the screen in screen mode (like DISPLAY/REFRESH). 
CTRL/Z ends a debugging session (like EXIT). 





FORMAT 





DESCRIPTION For an explanation of the CTRL/W and CTRL/Z commands, see the 
descriptions of the DISPLAY/REFRESH and EXIT commands, respectively. 
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CTRL/Y 


CTRL/Y 


When entered from DCL level, interrupts an image that is running without 
debugger control, enabling you to then invoke the debugger with the DCL 
DEBUG command. 


Note: Do not use CTRL/Y from within a debugging session. Instead, use 
CTRL/C or an equivalent abort-key sequence established with the SET 
ABORT_KEY command. 








FORMAT 
DESCRIPTION Pressing CT'RL/Y at DCL level enables you to interrupt an image that 


is running without debugger control, so that you can then invoke the 
debugger with the DCL DEBUG command. 


Note that you can bring an image under debugger control only if, as 

a minimum, that image was linked with the /TRACEBACK command 
qualifier (TRACEBACK is a LINK command default). Also, you can 
reference all of the image’s symbols while debugging only if its modules 
were compiled and linked with the /DEBUG command qualifier (in that 
case, you could use the DCL command RUN/NODEBUG to execute the 
image without the debugger). 


When you press CTRL/Y to interrupt the image’s execution, control is 
passed to the DCL command interpreter. If you then type the DCL 
DEBUG command, the interrupted image is brought under control of 
the debugger. The debugger sets its language dependent parameters to 
the source language of the module in which execution was interrupted 
and displays its prompt. You can then determine where execution 
was suspended by entering a SHOW CALLS command (and a SHOW 
PROCESS command, in the case of a multiprocess program). 


When a new debugging session is started, a process is created to run the 
main debugger image (DEBUGSHR.EXE) that controls the session. The 
main debugger process is a subprocess of the process that is running the 
image to be debugged. The debugger displays its banner when a new 
session is started. 


Other details about the effect of a CTRL/Y—DEBUG sequence depend on 
the debugging configuration (default or multiprocess), which is determined 
by the current definition of the logical name DBG$PROCESS in the 
process where the interrupted image was executing. 


Default Debugging Configuration 


The default debugging configuration is achieved when DBG$PROCESS is 
either undefined or has the value DEFAULT. In this case a new default 
debugging session is started every time you invoke the debugger with the 
CTRL/Y—DEBUG sequence (see Example 1). 
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CTRL/Y 


Multiprocess Debugging Configuration 


The multiprocess debugging configuration is achieved when 
DBG$PROCESS has the job definition MULTIPROCESS. In this case, 
the effect of a CTRL/Y—DEBUG sequence is as follows: 


¢ Ifa multiprocess debugging session does not already exist in the same 
job as the process running the interrupted image, a new multiprocess 
debugging session is created (see Example 2). 


e Ifa multiprocess debugging session already exists in the same job, the 
interrupted image and its process come under control of that session. 
In this case the debugger does not display its banner. 


Note that, within a debugging session, you can use the CONNECT 
command to connect an image that is running without debugger control in 
another process (of the same job) to that debugging session. 


Related commands: ($) DEBUG, CONNECT, CTRL/C. 





EXAMPLES 


$ RUN/NODEBUG TEST B 


Interrupt 


S$ DEBUG 
VAX DEBUG Version 5.4 


SDEBUG-~I-INITIAL, language is ADA, module set to SWAP 
DBG> 


The RUN/NODEBUG command executes the image TEST_B without 
debugger control. Execution is interrupted with CTRL/Y. The DEBUG 
command then causes the debugger to be invoked. The debugger displays 
its banner, sets the language-dependent parameters to the language (Ada, 
in this case) of the module (SWAP) in which execution was interrupted, 
and displays the prompt. This is the default debugging configuration, as 
indicated by the DBG> prompt. 


S$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 
S$ RUN/NODEBUG PROG2 


Interrupt 


S$ DEBUG 
VAX DEBUG Version 5.4 


SDEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in SPROCESS NUMBER 1 
DBG 1> 
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CTRL/Y 


The DEFINE/JOB command establishes a multiprocess debugging configuration. The RUN 
/NODEBUG command executes the image PROG2 without debugger control. The CTRL/Y— 
DEBUG sequence interrupts execution and invokes the debugger. The VAX DEBUG banner 
indicates that a new debugging session has been started. The process-specific prompt (DBG_ 
1>) indicates that this is a multiprocess configuration and that execution is suspended in process 


1, which is running PROG2. The activation tracepoint indicates where execution was interrupted 
when the debugger took control of the process. 
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DECLARE 


DECLARE 


Declares a formal parameter within a command procedure. This enables you 
to pass an actual parameter to the procedure when entering an @ (Execute 
Procedure) command. 





FORMAT 


DECLARE p-name:p-kind [,p-name:p-kindf, ... ]] 





PARAMETERS 


p-name 
Specifies a formal parameter (a symbol) that is declared within the 
command procedure. 


Do not specify a null parameter (represented either by two consecutive 
commas or by a comma at the end of the command). 


p-kind 
Specifies the parameter kind of a formal parameter. Valid keywords are as 
follows: 


ADDRESS Specifies that the actual parameter is interpreted as an address 
expression. Has the same effect as the command DEFINE/ADDRESS 
p-name = actual-parameter. 


COMMAND Specifies that the actual parameter is interpreted as a command. 
Has the same effect as the command DEFINE/COMMAND p-name = 
actual-parameter. 


VALUE Specifies that the actual parameter is interpreted as a value 
expression in the current language. Has the same effect as the 
command DEFINE/VALUE p-name = actual-parameter. 





DESCRIPTION 
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The DECLARE command is valid only within a command procedure. 


The DECLARE command binds one or more actual parameters (specified 
on the command line following the "@ file-spec") to formal parameters 
(symbols) declared within a command procedure. 


Each p-name:p-kind pair specified by a DECLARE command binds one 
formal parameter to one actual parameter. Formal parameters are bound 
to actual parameters in the order in which the debugger processes the 
parameter declarations. If you specify several formal parameters on a 
single DECLARE command, the leftmost formal parameter is bound to 
the first actual parameter, the next formal parameter is bound to the 
second, and so on. If you use a DECLARE command in a loop, the formal 
parameter is bound to the first actual parameter on the first iteration 

of the loop; the same formal parameter is bound to the second actual 
parameter on the next iteration, and so on. 


Each parameter declaration acts like a DEFINE command: it associates 
a formal parameter with an address expression, a command, or a value 
expression in the current language, according to the parameter kind 
specified. The formal parameters themselves are consistent with those 


DECLARE 


accepted by the DEFINE command and can in fact be deleted from the 
symbol table with the DELETE command. For more information, see the 
descriptions of the DEFINE and DELETE commands. 


The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a 
command procedure. The value of Z%PARCNT is the number of actual 
parameters passed to the command procedure. 


Related commands: @ (Execute Procedure), DEFINE, DELETE. 





EXAMPLES 


! *x*k**k*k*k Command Procedure EXAM.COM **x*x**x 
SET OUTPUT VERIFY 
DECLARE K:ADDRESS 


EXAMINE K 


DBG> @EXAM ARR4 


SDEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE K:ADDRESS 


EXAMINE K 
PROG _8\ARR4 
(1): 

(2)3 
(3): 

(4): 


ie 
1 
0 
1 


SDEBUG-I-VERIFYIC, exiting command procedure EXAM 


DBG> 


In this example, the command DECLARE K:ADDRESS declares the formal 
parameter K within command procedure EXAM.COM. When EXAM.COM 
is executed, the actual parameter passed to EXAM.COM is interpreted as 
an address expression, and the command EXAMINE K displays the value 
of that address expression. The command SET OUTPUT VERIFY causes 
the commands to echo when they are read by the debugger. 

At the debugger prompt, the command @EXAM ARR4 executes 
EXAM.COM, passing the actual parameter ARR4. Within EXAM.COM, 
ARR4 is interpreted as an address expression (an array variable, in this 
case). 


f **xx* Debugger Command Procedure EXAM GO.COM **x*xx** 
DECLARE L:ADDRESS, M: COMMAND 


EXAMINE L; M 


DBG> @EXAM GO X "@DUMP" 


In this example, the command procedure EXAM_GO.COM accepts two 
parameters, an address expression (L) and a command string (M). The 
address expression is then examined and the command is executed. 


At the debugger prompt, the command @EXAM_GO X "@DUMP" executes 
EXAM_GO.COM, passing the address expression X and the command 
string @DUMP. 
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DECLARE 


{| **xx** Debugger Command Procedure VAR.DBG ***** 
SET OUTPUT VERIFY 
FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 


DBG> @VAR.DBG 12,37,45 
SDEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 


SDEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 
DBG> 


In this example, the command procedure VAR.DBG accepts a variable 
number of parameters. That number is stored in the built-in symbol 
%PARCNT. 


At the debugger prompt, the command @VAR.DBG executes VAR.DBG, 
passing the actual parameters 12, 37, and 45. Therefore, ZPARCNT has 
the value 3, and the FOR loop is repeated 3 times. The FOR loop causes 
the DECLARE command to bind each of the three actual parameters 
(starting with 12) to a new declaration of X. Each actual parameter 

is interpreted as a value expression in the current language, and the 
command EVALUATE X displays that value. 
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DEFINE 


DEFINE 


Assigns a symbolic name to an address expression, command, or value. 





FORMAT 


DEFINE symbol-name=parameter 
[, symbol-name=parametery,...]] 





PARAMETERS 


symbol-name 

Specifies a symbolic name to be assigned to an address, command, or 
value. The symbolic name can be composed of alphanumeric characters 
and underscores. The debugger converts lowercase alphabetic characters 
to uppercase. The first character must not be a number. The symbolic 
name must be no more than 31 characters long. 


Par ameter 
Depends on the qualifier specified. 





QUALIFIERS 


/ADDRESS 


Specifies that the defined symbol is an abbreviation for an address 
expression. In this case, parameter is an address expression. DEFINE 
/ADDRESS is the default. 


/COMMAND 


Specifies that the defined symbol is treated as a new debugger command. 
In this case, parameter is a quoted character string. This qualifier 
provides, in simple cases, essentially the same capability as the DCL 
command "symbol:=string." To define complex commands, you might need 
to use command procedures with formal parameters. For more information 
about declaring parameters to command procedures, see the description of 
the DECLARE command. 


/LOCAL 

Specifies that the definition remain local to the command procedure in 
which the DEFINE command is issued. The defined symbol is not visible 
at the debugger command level. By default, a symbol defined within a 
command procedure is visible outside that procedure. 


/VALUE 


Specifies that the defined symbol is an abbreviation for a value. In this 
case, parameter is a language expression in the current language. 





DESCRIPTION 


The DEFINE/ADDRESS command enables you to assign a symbolic name 
o an address expression in your program. For example, you can define 

a symbol for a nonsymbolic program location or for a symbolic program 

location having a long path name prefix. Then, you can refer to that 
program location by the newly defined symbol. The /ADDRESS qualifier is 

the default definition qualifier. 
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DEFINE 


The DEFINE/COMMAND command enables you to define abbreviations 
for debugger commands or even define new commands, either from the 
debugger command level or from command procedures. 


The DEFINE/VALUE command enables you to assign a symbolic name to 
a value (or the result of evaluating a language expression). 


Use the /LOCAL qualifier to confine symbol definitions to command 
procedures. By default, defined symbols are global (visible outside the 
command procedure). 


If you plan to enter several DEFINE commands with the same qualifier, 
you can first use the SET DEFINE command to establish a new default 
qualifier (for example, SET DEFINE COMMAND makes the DEFINE 
command behave like DEFINE/COMMAND). Then you do not have to 
use that qualifier with the DEFINE command. You can override the 
current default qualifier for the duration of a single DEFINE command by 
specifying another qualifier. 


In symbol translation, the debugger searches symbols you define during 
the debugging session first. So if you define a symbol that already exists in 
your program, the debugger translates the symbol according to its defined 
definition, unless you specify a path name prefix. 


If a symbol is redefined, the previous definition is canceled, even if 
different qualifiers were used with the DEFINE command. 


Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE 
commands are available only when the image in whose context they 
were created is the current image. If you use the SET IMAGE command 
to establish a new current image, these definitions are temporarily 
unavailable. Definitions created with the DEFINE/COMMAND and 
DEFINE/KEY commands are always available for all images, however. 


Use the SHOW SYMBOL/DEFINED command to determine the 


equivalence value of a symbol. 
Use the DELETE command to cancel a symbol definition. 


Related commands: SHOW DEFINE, SHOW SYMBOL/DEFINED, 
DELETE, SET IMAGE, DECLARE. 





EXAMPLES 


DBG> DEFINE CHK=MAIN\LOOP+10 


This command assigns the symbol CHK to the address MAIN\ LOOP+10. 
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DEFINE 


DBG> DEFINE/VALUE COUNTER=0 
DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1) 


In this example, the first command assigns a value of 0 to the symbol 
COUNTER. The second command causes the debugger to increment the 
value of the symbol COUNTER by 1 whenever address R is encountered. 
In other words, this example counts the number of calls to R. 


DBG> DEFINE/COMMAND BRE = "SET BREAK" 


This command assigns the symbol BRE to the debugger command SET 
BREAK. 
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DEFINE/KEY 


DEFINE/KEY 


Assigns a string to a function key. 





FORMAT DEFINE/KEY key-name «equiv-string: 





PARAMETERS key-name 


Specifies a function key to be assigned a string. Valid key names are as 


follows: 
Key-name LK201 Keyboard VT100-type VT52-type 
PF1 PF1 PF1 Blue 
PF2 PF2 PF2 Red 
PF3 PF3 PF3 Black 
PF4 PF4 PF4 
KPO — KP9 Keypad 0 — 9 Keypad 0 — 9 Keypad 0 — 9 
PERIOD Keypad period (.) Keypad period (.) 
COMMA Keypad comma (,) Keypad comma (,) 
MINUS Keypad minus (—) Keypad minus (—) 
ENTER ENTER ENTER ENTER 
E4 Find 
E2 Insert Here 
E3 Remove 
E4 Select 
E5 Prev Screen 
E6 Next Screen 
HELP Help 
DO Do 
F6 — F20 F6 — F20 
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On LK201 keyboards: 
e You cannot define keys F1 to F5 or the arrow keys (E7 to E10). 


e You can define keys F6 to F14 only if you have first entered the DCL 
command SET TERMINAL/NOLINE_EDITING. In that case, the line- 
editing functions of the LEFT and RIGHT arrow keys (E8 and E9) are 


disabled. 


equiv-string 
Specifies the string to be processed when the specified key is pressed. 
Typically, this is one or more debugger commands. If the string includes 
any space or nonalphanumeric characters (for example, a semicolon 
separating two commands) enclose the string in quotation marks ("). 


DEFINE/KEY 





QUALIFIERS 


/ECHO (default) 
/NOECHO 


Controls whether the command line is displayed after the key has been 
pressed. Do not use /NOECHO with /NOTERMINATE. 


/|IF_STATE=(state-namef, ... ]) 
/NOIF_STATE (default) 


Specifies one or more states to which a key definition applies. The /IF_ 
STATE qualifier assigns the key definition to the specified states. You can 
specify predefined states, such as DEFAULT and GOLD, or user-defined 
states. A state name can be any appropriate alphanumeric string. The 
/NOIF_STATE qualifier assigns the key definition to the current state. 


/LOCK_STATE 


/NOLOCK_ STATE (default) 

Controls how long the state set by /SET_STATE remains in effect after 
the specified key is pressed. The /LOCK_STATE qualifier causes the state 
to remain in effect until it is changed explicitly (for example, with a SET 
KEY/STATE command). The /NOLOCK_STATE qualifier causes the state 
to remain in effect only until the next terminator character is typed, or 
until the next defined function key is pressed. 


/LOG (default) 
/NOLOG 


Controls whether a message is displayed indicating that the key definition 
has been successfully created. The /LOG qualifier displays the message. 


/SET STATE=state-name 
/NOSET_ STATE (default) 


Controls whether pressing the key changes the current key state. The 
/SET_STATE qualifier causes the current state to change to the specified 
state when you press the key. The /NOSET_STATE qualifier causes the 
current state to remain in effect. 


/TERMINATE 
/NOTERMINATE (default) 


Controls whether the specified string is terminated (processed) when 
the key is pressed. The /TERMINATE qualifier causes the string to be 
terminated when the key is pressed. The /NOTERMINATE qualifier 
allows you to press other keys before terminating the string by pressing 
the Return key. 





DESCRIPTION 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use 
this command. Keypad mode is enabled by default. 


The DEFINE/KEY command enables you to assign a string to a function 
key, overriding any predefined function that was bound to that key (the 
predefined key functions are listed in Appendix B). When you then press 
the key, the debugger enters the currently associated string into your 
command line. The DEFINE/KEY command is like the DCL DEFINE 
/KEY command. 
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DEFINE/KEY 


On VT52 and VT100-series terminals, the function keys you can use 
include all of the numeric keypad keys. Newer terminals and workstations 
have the LK201 keyboard. On LK201 keyboards, the function keys you 
can use include all of the numeric keypad keys, the nonarrow keys of the 
editing keypad (Find, Insert Here, and so on), and keys F6 to F20 at the 
top of the keyboard. 


A key definition remains in effect until you redefine the key, enter the 
DELETE/KEY command for that key, or exit the debugger. You can 
include key definitions in a command procedure, such as your debugger 
initialization file. 


The /IF_STATE qualifier enables you to increase the number of key 
definitions available on your terminal. The same key can be assigned 
any number of definitions as long as each definition is associated with a 
different state. 


By default, the current key state is the "DEFAULT" state. The current 
state can be changed with the SET KEY/STATE command, or by pressing 
a key that causes a state change (a key that was defined with the DEFINE 
/KEY/LOCK_STATE/STATE qualifier combination). 


Related commands: DELETE/KEY, SHOW KEY, SET KEY. 





EXAMPLES 


DBG> SET KEY/STATE=GOLD 


SDEBUG-I-SETKEY, 


keypad state has been set to GOLD 


DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX" 
SDEBUG-I-DEFKEY, GOLD key KP9 has been defined 


DBG> 


In this example, the SET KEY command establishes GOLD as the 
current key state. The DEFINE/KEY command assigns the SET RADIX 
/OVERRIDE HEX command to keypad key 9 for the current state (GOLD). 
The command is processed when the key is pressed. 


DBG> DEFINE/KEY/IF_ STATE=BLUE KP9 "SET BREAK %LINE " 
SDEBUG-I-DEFKEY, BLUE key KP9 has been defined 


DBG> 
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This command assigns the unterminated command string "SET BREAK 
%LINE" to keypad key 9 for the BLUE state. After pressing the keypad 
key sequence BLUE—KP9, you can enter a line number and then press 
the Return key to terminate and process the SET BREAK command. 


DEFINE/KEY 


DBG> SET KEY/STATE=DEFAULT 
SDEBUG-I-SETKEY, keypad state has been set to DEFAULT 
DBG> DEFINE/KEY/SET STATE=RED/LOCK STATE F12 "" 


SDEBUG-I-DEFKEY, DEFAULT key F12 has been defined 
DBG> 


In this example, the SET KEY command establishes DEFAULT as the 
current state. The DEFINE/KEY command makes key F12 (LK201 
keyboard) a state key. Pressing F12 while in the DEFAULT state causes 
the current state to become RED. The key definition is not terminated and 
has no other effect (a null string is assigned to F12). After pressing F12, 


you can enter "RED" commands by pressing keys that have definitions 
associated with the RED state. 
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DEFINE/PROCESS GROUP 


DEFINE/PROCESS_GROUP 


Note: This command applies to a multiprocess debugging configuration 
(when DBG$PROCESS has the value MULTIPROCESS). 


Assigns a symbolic name to a list of process specifications. 





FORMAT DEFINE/PROCESS GROUP process-group-name 
[=process-specj, ... |] 





PARAMETERS /process-group-name 
Specifies a symbolic name to be assigned to a list of process specifications. 
The symbolic name can be composed of alphanumeric characters and 
underscores. The debugger converts lowercase alphabetic characters to 
uppercase. The first character must not be a number. The symbolic name 
must be no more than 31 characters long. 


process-spec 


Specifies a process. Use any of the following forms: 


[%PROCESS_ NAME] process-name The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

[%PROCESS_ NAME] "process-name" The VMS process name, if that 
name contains space or lowercase 
characiers. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


%PROCESS PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number (or The number assigned to a process 


%PROC process-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 


/PROCESS_ GROUP command to 
represent a group of processes. 
Do not specify a recursive symbol 
definition. 


%NEXT_ PROCESS The process after the visible process in 
the debugger’s circular process list. 


%PREVIOUS_PROCESS The process previous to the visible 
process in the debugger’s circular 
process list. 
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DEFINE/PROCESS_GROUP 


%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


If you do not specify a process, the symbolic name is created but contains 
no process entries. 





DESCRIPTION 


The DEFINE/PROCESS_GROUP command assigns a symbol to list of 
process specifications. You can then use the symbol in any command 
where a list of process specifications is allowed. 


The DEFINE/PROCESS_GROUP command does not verify the existence 


of a specified process. This enables you to specify processes that do not yet 
exist. 


To identify a symbol that was defined with the DEFINE/PROCESS _ 
GROUP command, use the SHOW SYMBOL/DEFINED command. To 
delete a symbol that was defined with the DEFINE/PROCESS_GROUP 
command, use the DELETE command. 


Related commands: SHOW SYMBOL/DEFINED, DELETE, SET DEFINE, 
SHOW DEFINE. 





EXAMPLES 


DBG_1> DEFINE/PROCESS GROUP SERVERS=FILE_ SERVER, NET SERVER 
DBG_1> SHOW PROCESS SERVERS 


Number Name Hold State Current PC 
* a3 FILE SERVER step FS PROG\SLINE 37 
2 NETWORK SERVER break NET PROG\SLINE 24 


DBG_1> 


This DEFINE/PROCESS_GROUP command assigns the symbolic 
name SERVERS to the process group consisting of FILE_SERVER 
and NETWORK_SERVER. The SHOW PROCESS SERVERS command 


displays information about the processes that make up the group 
SERVERS. 


USER_3> DEFINE/PROCESS GROUP G1=%PROCESS NUMBER 1,%VISIBLE_ PROCESS 


defined Gl 


_USER_3> SHOW SYMBOL/DEFINED G1 


bound to: "SPROCESS NUMBER 1, sVISIBLE PROCESS" 
was defined /process_ group 
USER_3> DELETE Gl 


This DEFINE/PROCESS_GROUP command assigns the symbolic name 
G1 to the process group consisting of process 1 and the visible process 
(process 3). The command SHOW SYMBOL/DEFINED G1 identifies the 
defined symbol G1. The command DELETE G1 deletes the symbol from 
the DEFINE symbol table. 
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DEFINE/PROCESS GROUP 


i 
fH Ww 


DBG_2> DEFINE/PROCESS GROUP A 
DBG_ 2> DEFINE/PROCESS GROUP B = 
DBG_2> DEFINE/PROCESS GROUP E = I 
SDEBUG-E-NORECSYM, recursive PROCESS GROUP symbol definition 

encountered at or near "A" 
DBG_2> 


7C,D 
,F,G 
7J,A 


~ ~ = 


This series of DEFINE/PROCESS_GROUP commands illustrate valid and 
invalid uses of the command. 
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DELETE 


Deletes a symbol! definition that was established with the DEFINE command. 





FORMAT DELETE /[symbol-name[,... |] 





PARAMETERS symbol-name 
Specifies a symbol whose definition is to be deleted from the DEFINE 
symbol table. Do not use the asterisk wildcard character (*). Do not 
specify a symbol name with /ALL. If you use /LOCAL, the symbol specified 
must have been previously defined with the DEFINE/LOCAL command. If 
you do not specify /LOCAL, the symbol specified must have been previously 
defined with the DEFINE command without the /LOCAL qualifier. 





QUALIFIERS /ALL 
Deletes all global DEFINE definitions. If you also specify /LOCAL, 
deletes all local DEFINE definitions associated with the current command 
procedure (but not the global DEFINE definitions). Do not specify a 
symbol name with /ALL. 


/LOCAL 


Deletes the (local) definition of the specified symbol from the current 
command procedure. The symbol must have been previously defined with 
the DEFINE/LOCAL command. 





DESCRIPTION The DELETE command deletes either a global DEFINE symbol or a local 
DEFINE symbol. A global DEFINE symbol is a symbol defined with the 
DEFINE command without the /LOCAL qualifier. A local DEFINE symbol 
is a symbol defined in a debugger command procedure with the DEFINE 
/LOCAL command, so that its definition is confined to that command 
procedure. 


Related command: DEFINE, SHOW SYMBOL/DEFINED, SHOW 
DEFINE, DECLARE. 





EXAMPLES 


DBG> DEFINE X = INARR, Y = OUTARR 
DBG> DELETE x,Y 


In this example, the DEFINE command defines X and Y as global symbols 
corresponding to INARR and OUTARR, respectively. The DELETE 
command deletes these two symbol definitions from the global symbol 
table. 
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DBG> DELETE/ALL/LOCAL 


In this example, the DELETE/ALL/LOCAL commmand deletes all local 
symbol definitions from the current command procedure. 
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DELETE/KEY 


Deletes a key definition that was established with the DEFINE/KEY command 
or, by default, by the debugger. 











FORMAT DELETE/KEY [key-name] 

PARAMETERS key-name 
Specifies a key whose definition is to be deleted. Do not use the asterisk 
wildcard character (*). Do not specify a key name with /ALL. Valid key 
names are as follows: 

Key-name LK201 Keyboard VT100-type VT52-type 

PF1 PF1 PF1 Blue 

PF2 PF2 PF2 Red 

PF3 PF3 PF3 Black 

PF4 PF4 PF4 

KPO — KP9 Keypad 0-9 Keypad 0 — 9 Keypad 0 — 9 

PERIOD Keypad period (.) Keypad period (.) 

COMMA Keypad comma (,) Keypad comma (,) 

MINUS Keypad minus (—) Keypad minus (—) 

ENTER ENTER ENTER ENTER 

E1 Find 

E2 Insert Here 

E3 Remove 

E4 Select 

E5 Prev Screen 

E6 Next Screen 

HELP Help 

DO Do 

F6 — F20 F6 — F20 

QUALIFIERS /ALL 


Deletes all key definitions in the specified state. Do not specify a key name 
with /ALL. If you do not specify a state, all key definitions in the current 
state are deleted. Use the /STATE qualifier to specify one or more states. 


/LOG (default) 


/NOLOG 


Controls whether a message is displayed indicating that the specified key 
definitions have been deleted. The /LOG qualifier displays the message. 
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/STATE=(state-name [, ... ]) 
/NOSTATE (default) 


Selects one or more states for which a key definition is to be deleted. The 
/STATE qualifier deletes key definitions for the specified states. You can 
specify predefined key states, such as DEFAULT and GOLD, or user- 
defined states. A state name can be any appropriate alphanumeric string. 
The /NOSTATE qualifier deletes the key definition for the current state 
only. 


By default, the current key state is the "DEFAULT" state. The current 
state can be changed with the SET KEY/STATE command, or by pressing 
a key that causes a state change (a key that was defined with the DEFINE 
/KEY/LOCK_STATE/STATE qualifier combination). 








DESCRIPTION The DELETE/KEY command is like the DCL DELETE/KEY command. 
Keypad mode must be enabled (SET MODE KEYPAD) before you can use 
this command. Keypad mode is enabled by default. 

Related commands: DEFINE/KEY, SHOW KEY, SET KEY. 

EXAMPLES 


DBG> DELETE/KEY KP4 
SDEBUG-I-DELKEY, DEFAULT key KP4 has been deleted 


DBG> 


i 


This command deletes the key definition for keypad key KP4 in the state 
last set by the SET KEY command (by default, this is the DEFAULT 
state). 


DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA 


SDEBUG-I-DELKEY, BLUE key COMMA has been deleted 
sDEBUG-I-DELKEY, RED key COMMA has been deleted 


DBG> 
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This command deletes the key definition for keypad key COMMA in the 
BLUE and RED states. 


DEPOSIT 


DEPOSIT 


Changes the value of a program variable. More generally, deposits a new 
value at the location denoted by an address expression. 





FORMAT 


DEPOSIT address-expression = language-expression 





PARAMETERS 


address-expression 

Specifies the location into which the value of the language expression is 
to be deposited. With high-level languages, this is typically the name of 
a variable and can include a path name to specify the variable uniquely. 
More generally, an address expression can also be a memory address or 
a register and can be composed of numbers (offsets) and symbols, as well 
as one or more operators, operands, or delimiters. Appendix D identifies 
the debugger’s built-in symbols for the VAX registers and identifies the 
operators that can be used in address expressions. 


You cannot specify an entire aggregate variable (a composite data 
structure such as an array or a record). To specify an individual array 
element or a record component, use the syntax of the current language. 


See Chapter 11 for information that is specific to vector registers and 
vector instructions. 


language-expression 

Specifies the value to be deposited. You can specify any language 
expression that is valid in the current language. For most languages, 

the expression can include the names of simple (noncomposite, single- 
valued) variables but not the names of aggregate variables (such as arrays 
or records). If the expression contains symbols with different compiler 
generated types, the debugger uses the rules of the current language to 
evaluate the expression. 


If the expression is an ASCII string or a VAX assembly-language 
instruction, you must enclose it in quotation marks (") or apostrophes 
(’). If the string contains quotation marks or apostrophes, use the other 
delimiter to enclose the string. 


If the string has more characters (1-byte ASCII) than can fit into the 
program location denoted by the address expression, the debugger 
truncates the extra characters from the right. If the string has fewer 
characters, the debugger pads the remaining characters to the right of the 
string by inserting ASCII space characters. 





QUALIFIERS 


/ASCIC 


Deposits a counted ASCII string into the specified location. You must 
specify a string on the right-hand side of the equal sign. The deposited 
string is preceded by a 1-byte count field that gives the length of the 
string. The /AC qualifier is also accepted. 
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/ASCID | 

Deposits an ASCII string into the address given by a string descriptor 
that is at the specified location. You must specify a string on the right- 
hand side of the equal sign. The specified location must contain a 
string descriptor. If the string lengths do not match, the string is either 
truncated on the right or padded with space characters on the right. /AD 
is also accepted. 


/ASCII:n 

Deposits n bytes of an ASCII string into the specified location. You must 
specify a string on the right-hand side of the equal sign. If its length is 
not n, the string is truncated or padded with space characters on the right. 
If n is omitted, the actual length of the data item at the specified location 
is used. 


/ASCIW 

Deposits a counted ASCII string into the specified location. You must 
specify a string on the right-hand side of the equal sign. The deposited 
string is preceded by a 2- byte count field that gives the length of the 
string. The /AW qualifier is also accepted. 


/ASCIZ 

Deposits a zero-terminated ASCII string into the specified location. You 
must specify a string on the right-hand side of the equal sign. The 
deposited string is terminated by a zero byte that indicates the end of 
the string. The /AZ qualifier is also accepted. 


/BYTE 


Deposits a 1-byte integer into the specified location. 


/D_FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
D_floating type (length 8 bytes) and deposits the result into the specified 
location. Values of type D_floating can range from .29 « 10728 to 1.7 « 10°8 
with approximately 16 decimal digits precision. 


/DATE_TIME 

Converts a string representing a date and time (for example, 21-DEC-1988 
21:08:47.15) to the VMS internal format for date and time and deposits 
that value (length 8 bytes) into the specified location. Specify an absolute 
date and time in the following format: /dd-mmm-yyyy[:/] [hh:mm:ss.cc]. 


/FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
F_ floating type (length 4 bytes) and deposits the result into the specified 
location. Values of type F_floating can range from .29 + 10~28 to 1.7 « 10°8 
with approximately 7 decimal digits precision. 


/G_FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
G_floating type (length 8 bytes) and deposits the result into the specified 
location. Values of type G_floating can range from 56 « 10739 to .9 x 1028 
with approximately 15 decimal digits precision. 


DEPOSIT 


/H_ FLOAT 


Converts the expression on the right-hand side of the equal sign to the 
H_floating type (length 16 bytes) and deposits the result into the specified 
location. Values of type H_floating can range from .84%10—4922 to .59*10492 
with approximately 33 decimal digits precision. 


AINSTRUCTION 


Deposits a VAX assembly-language instruction into the specified location. 
The expression on the right-hand side of the equal sign must be a string 
representing a VAX instruction. 


/LONGWORD 
Deposits a longword integer (length 4 bytes) into the specified location. 


/OCTAWORD 


Deposits an octaword integer (length 16 bytes) into the specified location. 


/PACKED:n 


Converts the expression on the right-hand side of the equal sign to a 
packed decimal representation and deposits the resulting value into the 
specified location. The value of n is the number of decimal digits. Each 
digit occupies one nibble (4 bits). 


/QUADWORD 


Deposits a quadword integer (length 8 bytes) into the specified location. 
/TASK 

Note: This qualifier applies to Ada programs. 

Deposits an Ada task value (a task name, or a task ID such as TASK 3) 
into the specified location. 

/TYPE=(type-expression) 

Converts the expression to be deposited to the type denoted by type- 
expression (the name of a variable or data type declared in the program), 


then deposits the resulting value into the specified location. This enables 
you to specify a user-declared type. 


You must use parentheses around the type expression. 


/WORD 
Deposits a word integer (length 2 bytes) into the specified location. 





DESCRIPTION 


The DEPOSIT command can be used to change the contents of any 
memory location or register that is accessible in your program. For high- 
level languages the command is used mostly to change the value of a 
variable (an integer, real, string, array, record, and so on). 


The DEPOSIT command is like an assignment statement in most 
programming languages. The value of the expression specified to the right 
of the equal sign is assigned to the variable or other location specified to 
the left of the equal sign. Note that for Ada and Pascal, you can use ":=" 
instead of "=" in the command syntax. 
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The debugger recognizes the compiler generated types associated with 
symbolic address expressions (symbolic names declared in your program). 
Symbolic address expressions include the following entities: 


e Variable names. When specifying a variable with the DEPOSIT 
command, use the same syntax that is used in the source code. 


¢ Routine names, labels, and line numbers. These are associated with 
VAX instructions. You can deposit instructions using basically the 
same techniques as when depositing into string variables. However, 
you must also use the /INSTRUCTION qualifier or first enter a SET 
TYPE INSTRUCTION or SET TYPE/OVERRIDE INSTRUCTION 
command. 


In general, when you enter a DEPOSIT command, the debugger takes the 
following action: 


e It evaluates the address expression specified to the left of the equal 
sign, to yield a program location. 


e Ifthe program location has a symbolic name, the debugger associates 
the location with the symbol’s compiler generated type. If the location 
does not have a symbolic name (and, therefore, no associated compiler 
generated type) the debugger associates the location with the type 
longword integer by default. This means that, by default, you can 
deposit integer values that do not exceed 4 bytes into these locations. 


See Chapter 11 for information that is specific to vector registers and 
vector instructions. 


e It evaluates the language expression specified to the right of the equal 
sign, in the syntax of the current language and in the current radix, to 
yield a value. The current language is the language last established 
with the SET LANGUAGE command. If no SET LANGUAGE 
command was entered, the current language is, by default, the 
language of the module containing the main program. 


e It checks that the value and type of the language expression is 
consistent with the type of the address expression. If you try to 
deposit a value that is incompatible with the type of the address 
expression, the debugger issues a diagnostic message. If the value is 
compatible, the debugger deposits the value into the location denoted 
by the address expression. 


The debugger might do type conversion during a deposit operation if the 
language rules allow it. For example a real value that is specified to the 
right of the equal sign might be converted to an integer value if it is being 
deposited into a location with an integer type. In general, the debugger 
tries to follow the assignment rules for the current language. 


There are several ways of changing the type associated with a program 
location so that you can deposit data of a different type into that location: 


¢ To change the default type for all locations that do not have a symbolic 
name, you can specify a new type with the SET TYPE command. 


DEPOSIT 


¢ To change the default type for all locations (both those that do and do 
not have a symbolic name), you can specify a new type with the SET 
TYPE/OVERRIDE command. 


¢ To override the type currently associated with a particular location for 
the duration of a single DEPOSIT command, you can specify a new 
type by means of a qualifier (/ASCII:n, /BYTE, TYPE=(type-expression), 
and so on). 


The debugger can interpret and display integer data in any one of four 
radixes: binary, decimal, hexadecimal, and octal. The default radix for 
both data entry and display is decimal for all languages except BLISS 
and MACRO. It is hexadecimal for BLISS and MACRO. You can use the 
SET RADIX and SET RADIX/OVERRIDE commands to change the default 
radix. 


The DEPOSIT command sets the current entity built-in symbols 
%CURLOC and period (.) to the location denoted by the address 
expression specified. Logical predecessors (ZPREVLOC and circumflex 
(4)) and successors (%NEXTLOC and pressing the Return key) are based 
on the value of the current entity. 


Related commands: EXAMINE, EVALUATE, (SET, SHOW, CANCEL) 
RADIX, (SET, SHOW) TYPE, CANCEL TYPE/OVERRIDE. 





EXAMPLES 

DBG> DEPOSIT 
DBG> DEPOSIT 
DBG> DEPOSIT 
DBG> DEPOSIT 
DBG> DEPOSIT 


CS y 
This command deposits the value 7 into the integer variable I. 
WIDTH = CURRENT WIDTH + 24.80 


This command deposits the value of the expression CURRENT_WIDTH + 
24.80 into the real variable WIDTH. 


STATUS = FALSE 


This command deposits the value FALSE into the Boolean variable 
STATUS. 


PART NUMBER = "WG-7619.3-84" 


This command deposits the string WG-7619.3-84 into the string variable 
PART_NUMBER. 


EMPLOYEE.ZIPCODE = 02172 


This command deposits the value 02172 into component ZIPCODE of 
record EMPLOYEE. 
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DBG> DEPOSIT ARR(8) = 35 
DBG> DEPOSIT * = 14 


The first DEPOSIT command deposits the value 35 into element 8 of 
array ARR. As a result, element 8 becomes the current entity. The second 
command deposits the value 14 into the logical predecessor of element 8, 
namely element 7. 


DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = QO) 


This command deposits the value 0 into elements 1 to 4 of array ARR. 


DBG>: DEPOSIT :-COLOR: = 3 


SDEBUG-E-OPTNOTALLOW, operator "DEPOSIT" not allowed on given 
data type 
DBG> 


The debugger alerts you when you try to deposit data of the wrong type 
into a variable (in this case, if you try to deposit an integer value into an 
enumerated type variable). The E (error) message severity indicates that 
the debugger does not make the assignment. 


DBG> DEPOSIT VOLUME = ~- 100 


SDEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near ’-’ 
DBG> 


The debugger alerts you when you try to deposit an out-of-bounds value 
into a variable (in this case a negative value). The I (informational) 
message severity indicates that the debugger does make the assignment. 


DBG> DEPOSIT/BYTE WORK = %HEX 21 


This command deposits the expression %HEX 21 into location WORK and 
converts it to a byte integer. 


DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555 


This command deposits the expression 111222333444555 into location 
BIGINT and converts it to an octaword integer. 


DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35 


This command converts 1.11949*10**35 to an F_floating type value and 
deposits it into location BIGFLT. 


DBG> DEPOSIT/ASCII:10 WORK+20 = ’abcdefghij’ 


This command deposits the string "abcdefghij" into the location that is 20 
bytes beyond that denoted by the symbol WORK. 


DBG> DEPOSIT/INSTR SUB2+2 = ‘MOVL #20A,RO0’ 


This command deposits the instruction MOVL #20A,RO0’ into the location 
SUB2 + 2 bytes. 
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DBG> DEPOSIT/TASK VAR = %STASK 2 
DBG> EXAMINE/HEX VAR 
SAMPLE.VAR: 0016A040 

DBG> EXAMINE/TASK VAR 
SAMPLE.VAR: STASK 2 

DBG> 


The DEPOSIT command deposits the Ada task value TASK 2 into 


location VAR. The subsequent EXAMINE commands display the contents 
of VAR in hexadecimal format and as a task value, respectively. 
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DISABLE AST 


Disables the delivery of asynchronous system traps (ASTs) in your program. 





FORMAT DISABLE AST 





DESCRIPTION The DISABLE AST command disables the delivery of ASTs in your 
program and thereby prevents interrupts from occurring while the 
program is running. If ASTs are delivered while the debugger is running 
(processing commands, and so on), they are queued and are delivered 
when control is returned to the program. 


The ENABLE AST command re-enables the delivery of ASTs, including 
any pending ASTs (ASTs waiting to be delivered). 


Related commands: (ENABLE, SHOW) AST. 





EXAMPLE 


DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 


The DISABLE AST disables the delivery of ASTs in your program, as 
confirmed with the SHOW AST command. 
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DISPLAY 


Creates a new screen display or modifies an existing display. 





FORMAT 


DISPLAY [disp-name [AT w-spec] [disp-kind] [, . . . J] 





PARAMETERS 


disp-name 
Specifies the display to be created or modified. 


If you are creating a new display, specify a name that is not already used 
as a display name. 


If you are modifying an existing display, you can specify any of the 
following entities: 


e A predefined display: SRC, OUT, PROMPT, INST, REG 
e Adisplay previously created with the DISPLAY command 


e A display built-in symbol: 2CURDISP, ZCURSCROLL, %NEXTDISP, 
%NEXTINST, SZNEXTOUTPUT, ZNEXTSCROLL, ZNEXTSOURCE ~ 


You must specify this parameter unless you use /(GENERATE (parameter 
optional), or /REFRESH (parameter not allowed). 


You can specify more than one display, each with an optional window 
specification (w-spec) and display kind (disp-kind). 


W-spec 
Specifies the screen window at which the display is to be positioned. You 
can specify any of the following entities: 


e A predefined window. For example, RH1 (right top half). See 
Appendix C. 


e A window definition previously established with the SET WINDOW 
command. 


¢ <A window specification of the form (start-line, line-count [,start-column, 
column-count]). The specification can include expressions which can 
be based on the built-in symbols PAGE and %2WIDTH (for example, 
%WIDTH/4). 


If you omit the w-spec parameter, the screen position depends on whether 
you are specifying an existing display or a new display: 


e If you are specifying an existing display, the position of the display is 
not changed. 


e If you are specifying a new display, it is positioned at window H1 or 
H2, alternating between H1 and H2 each time you create another 
display. 
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disp-kind 


Specifies the display kind. Valid keywords are as follows: 


DO (command; .. . }) 


INSTRUCTION 


INSTRUCTION (command) 


OUTPUT 


REGISTER 


SOURCE 


SOURCE (command) 


Specifies an automatically updated output display. 
The commands are executed in the order listed 
each time the debugger gains control. Their output 
forms the contents of the display. If you specify 
more than one command, they must be separated 
by semicolons. 


Specifies an instruction display. If selected as 
the current instruction display with the SELECT 
ANSTRUCTION command, it displays the output 
from subsequent EXAMINE/INSTRUCTION 
commands. 


Specifies an automatically updated instruction 
display. The command specified must be an 
EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 


Specifies an output display. If selected as the 
current output display with the SELECT/OUTPUT 
command, it displays any debugger output that is not 
directed to another display. If selected as the current 
input display with the SELECT/INPUT command, it 
echoes debugger input. If selected as the current 
error display with the SELECT/ERROR command, it 
displays debugger diagnostic messages. 


Specifies an automatically updated register display. 
The display is updated each time the debugger 
gains control. 


Specifies a source display. If selected as the 
current source display with the SELECT/SOURCE 
command, it displays the output from subsequent 
TYPE or EXAMINE/SOURCE commands. 


Specifies an automatically updated source display. 
The command specified must be a TYPE or 
EXAMINE/SOURCE command. The source display 
is updated each time the debugger gains control. 


You cannot change the display kind of the PROMPT display. 


If you omit the disp-kind parameter, the display kind depends on whether 
you are specifying an existing display or a new display: 


e If you are specifying an existing display, the display kind is not 


changed. 


e Ifyou are specifying a new display, an OUTPUT display is created. 





QUALIFIERS 
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/CLEAR 


Erases the entire contents of a specified display. Do not use /CLEAR when 
creating a new display. Do not use /GENERATE with /CLEAR. 


DISPLAY 


/DYNAMIC (default) 
/NODYNAMIC 


Controls whether a display automatically adjusts its window dimensions 
proportionally when the screen height or width is changed by a SET 
TERMINAL command. By default (DYNAMIC), all user-defined and 
predefined displays, adjust their dimensions automatically. 


/GENERATE 


Regenerates the contents of a specified display. Only automatically 
generated displays are regenerated. These include DO displays, register 
displays, source (cmd-list) displays, and instruction (cmd-list) displays. 
The debugger automatically regenerates all these kinds of displays before 
each prompt. If no display is specified, regenerates the contents of all 
automatically generated displays. Do not use (GENERATE when creating 
a new display. Do not use /CLEAR with /GENERATE. 


/HIDE 


Places a specified display at the bottom of the display pasteboard. This 
hides the specified display behind any other displays that share the same 
region of the screen. You cannot hide the PROMPT display. 


The /HIDE qualifier has the same effect as /PUSH. 


/MARK_CHANGE 


/NOMARK_CHANGE (default) 

Controls whether the lines that change in a DO display each time it is 
automatically updated are marked. When you use /MARK_CHANGEH, any 
lines in which some contents have changed since the last time the display 
was updated are highlighted in reverse video. This qualifier is particularly 
useful when you want any variables in an automatically updated display 
to be highlighted when they change. 


The /NOMARK_CHANGE qualifier (default) specifies that any lines that 
change in DO displays are not to be marked. This qualifier cancels the 
effect of a previously entered /MARK_ CHANGE qualifier on the specified 
display. 


This qualifier is not applicable to other kinds of displays. 


/POP (default) 


/NOPOP 

Controls whether a specified display is placed at the top of the display 
pasteboard, ahead of any other displays but behind the PROMPT display. 
By default (/POP), the display is placed at the top of the pasteboard 

and hides any other displays that share the same region of the screen, 
except for the PROMPT display. This is the default action of the DISPLAY 
command. 


The /NOPOP qualifier preserves the order of all displays on the pasteboard 
(same effect as /NOPUSH). 


/PROCESS|=(process-spec)] 


/NOPROCESS (default) 


Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 
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Controls whether the specified display is process specific—that is, whether 
the specified display is associated only with a particular process. The 
contents of a process-specific display are generated and modified in the 


context of that process. You can make any display process specific, except 
for the PROMPT display. 


The /PROCESS=(process-spec) qualifier causes the specified display to be 
associated with the specified process. You must include the parentheses. 
Use any of the following process-spec forms: 


[%PROCESS_NAME] process-name The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

[%PROCESS_ NAME] "process-name" The VMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


%PROCESS _PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number (or The number assigned to a process 


%PROC process-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol! defined with the DEFINE 


/PROCESS_GROUP command to 
represent a group of processes. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 

%PREVIOUS_PROCESS The process previous to the visible 
process in the debugger’s circular 
process list. 

%VISIBLE_PROCESS The process whose call stack, register 


set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


The /PROCESS qualifier causes the specified display to be associated with 
the process that was the visible process when the DISPLAY/PROCESS 
command was executed. 


The /NOPROCESS qualifier causes the specified display to always be 
associated with the visible process, which might change during program 
execution. This is the default behavior. 


If you do not specify /PROCESS, the current process-specific behavior (if 
any) of the specified display remains unchanged. 


See also /SUFFIX. 


DISPLAY 


/PUSH 


/NOPUSH 


The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH qualifier 
preserves the order of all displays on the pasteboard (same effect as 
/NOPOP). 


/REFRESH 


Refreshes the terminal screen. Do not specify any command parameters 
with /REFRESH. You can also use CTRL/W to refresh the screen. 


/REMOVE 


Marks the display as being removed from the display pasteboard, so it 
is not shown on the screen unless you explicitly request it with another 
DISPLAY command. Although a removed display is not visible on the 
screen, it still exists and its contents are preserved. You cannot remove 
the PROMPT display. 


/SIZE:n 


Sets the maximum size of a display to n lines. If more than n lines are 
written to the display, the oldest lines are lost as the new lines are added. 
If you omit this qualifier, the maximum size of the display is as follows: 


e If you specify an existing display, the maximum size is unchanged 


e Ifyou are creating a display, the default size is 64 lines 


For an output or DO display, /SIZE:n specifies that the display should hold 
the n most recent lines of output. For a source or instruction display, n 
gives the number of source lines or lines of instructions that can be placed 
in the memory buffer at any one time. However, you can scroll a source 
display over the entire source code of the module whose code is displayed 
(source lines are paged into the buffer as needed). Similarly, you can scroll 
an instruction display over all of the instructions of the routine whose 
instructions are displayed (instructions are decoded from the image as 
needed). 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS NAME The display-name suffix is the VMS process name. 


PROCESS NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_ PID The display-name suffix is the VMS process identification 
number (PID). 
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If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 


See also /[NO]PROCESS. 





DESCRIPTION 


The DISPLAY command can be used to create a display or modify an 
existing display. 


To create a display, specify a name that is not already used as a display 
name (the SHOW DISPLAY command identifies all existing displays). 


By default, the DISPLAY command places a specified display on top of the 
display pasteboard, ahead of any other displays but behind the PROMPT 
display, which cannot be hidden. The specified display thus hides the 
portions of other displays (except for the PROMPT display) that share the 
same region of the screen. 


See Appendix B for keypad-key definitions associated with the DISPLAY 
command. 


Related commands: (SHOW, CANCEL) DISPLAY, (SET, SHOW, 
CANCEL) WINDOW, SELECT, EXPAND, MOVE, CTRL/W, (SET, SHOW) 
TERMINAL, SET PROMPT. 





EXAMPLES 


DBG> DISPLAY REG 


This command shows the predefined register display, REG, at its current 
window location. 


DBG> DISPLAY/PUSH INST 


This command pushes display INST to the bottom of the display 
pasteboard, behind all other displays. 


DBG> DISPLAY NEWDISP AT RT2 
DBG> SELECT/INPUT NEWDISP 


In this example, the DISPLAY command shows the user-defined display 
NEWDISP at the right middle third of the screen. The SELECT/INPUT 
command selects NEWDISP as the current input display. NEWDISP now 
echoes debugger input. 


DBG> DISPLAY DISP2 AT RS45 
DBG> SELECT/OUTPUT DISP2 
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In this example, the DISPLAY command creates a display named DISP2 
essentially at the right bottom half of the screen, above the PROMPT 
display, which is located at S6. This is an output display by default. The 
SELECT/OUTPUT command then selects DISP2 as the current output 
display. 


DBG> 
DBG> 
DBG> 


DBG> 


DBG> 


DISPLAY 


SET WINDOW TOP AT (1,8,45,30) 
DISPLAY NEWINST AT TOP INSTRUCTION 
SELECT/INST NEWINST 


In this example, the SET WINDOW command creates a window named 
TOP starting at line 1 and column 45, and extending down for 8 lines 
and to the right for 30 columns. The DISPLAY command creates an 
instruction display named NEWINST to be displayed through TOP. The 
SELECT/INST command selects NEWINST as the current instruction 
display. 


DISPLAY CALLS AT Q3 DO (SHOW CALLS) 


This command creates a DO display named CALLS at window Q3. Each 
time the debugger gains control from the program, the SHOW CALLS 
command is executed and the output is displayed in display CALLS, 
replacing any previous contents. 


DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C) 


This command creates a DO display named EXAM at window Q2. The 
display shows the current values of variables A, B, and C whenever the 
debugger prompts for input. Any changed values are highlighted. 


DBG 3> DISPLAY/PROCESS OUT_X AT S4 


This command makes display OUT_X specific to the visible process 
(process 3) and puts the display at window S4. 


DBG 2> DISPLAY/PROCESS OUT /SUFFIX AT S45 OUTPUT 


This command creates an output display at window S45. The /PROCESS 
qualifier, by default, makes the display specific to the visible process 
(process 2, in this example). The /SUFFIX qualifier appends a process- 
identifying suffix, that denotes the visible process, to the display name 
OUT_. By default, the /SUFFIX qualifier appends the same process 
identifier suffix that appears on the prompt. Therefore, the full display 
name is OUT_2. 


CD-75 


0 


O 


Note: This command applies to a multiprocess debugging configuration 
(when DBG$PROCESS has the value MULTIPROCESS). 


Executes a debugger command in the context of one or more processes. 





FORMAT DO (command; ... ]) 





PARAMETERS command 


Specifies a debugger command that is to be executed in the context of the 
processes specified. 





QUALIFIERS /PROCESS=(process-specf, . . . ]) 


Specifies one or more processes in whose context the commands are 
executed. You must include the parentheses even if only one process is 
specified. If you do not specify /PROCESS, the commands are executed in 
the context of all processes (this effect is also achieved if you specify the 
asterisk wildcard character (*) for process-spec). 


Use any of the following forms: 


[%PROCESS_NAME] process-name The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

[%PROCESS_NAME] "process-name" The VMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number (or The number assigned to a process 


%PROC process-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 


/PROCESS_GROUP command to 
represent a group of processes. 


%NEXT_ PROCESS The process after the visible process in 
the debugger’s circular process list. 

%PREVIOUS_PROCESS The process previous to the visible 
process in the debugger’s circular 
process list. 
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%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 





DESCRIPTION _By default, commands are executed in the context of the visible process. 


The DO command enables you to execute commands in the context of one 
or more processes that are currently under debugger control (this is also 
referred to as "broadcasting" commands to processes). The DO command 
is equivalent to entering a SET PROCESS/VISIBLE command for each 
process specified with the /PROCESS qualifier (or for all processes, if 
/PROCESS is not specified) and then entering the specified commands. 


To change the visible process, use the SET PROCESS command. 


When using the DO command, note that a hold condition in the visible 
process (as established with the command SET PROCESS/HOLD) is 
ignored. 


Related commands: SET PROCESS. 





EXAMPLES 


DBG 2> DO (SHOW CALLS) 
For %PROCESS NUMBER 1 


module name routine name line rel PC abs PC 

*MOD 4 SUB3 31 OOOO001E OO000041E 
For tPROCESS NUMBER 2 

module name routine name line rel PC abs PC 

*MOD3 SUB1 4 OO0O00000B 00000408 
DBG 2> 


This command executes a SHOW CALLS command in the context of all 
processes that are currently under debugger control. 


DBG 3> DO/PROCESS=(%PROC 2,%PROC 1) (EVAL/ADDR X;EXAM X) 
For %PROCESS NUMBER 2 

SDEBUG-E-NOSYMBOL, symbol ’X’ is not in the symbol table 
For sProcess_ number 1 

512 

TEST\X: 1 
DBG 3> 


This command executes the two commands EVAL/ADDR X and EXAM X 
in the context of processes 2 and 1. 
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Invokes the editor established with the SET EDITOR command. If no SET 
EDITOR command was entered, invokes the VAX Language-Sensitive Editor, 
if that editor is installed on your system. 





FORMAT 


EDIT /[module-name\] line-number] 





PARAMETERS 


module-name 

Specifies the name of the module whose source file is to be edited. If you 
specify a module name, you must also specify a line number. If you omit 
the module name parameter, the source file whose code appears in the 
current source display is chosen for editing. 


line-number 

A positive integer that specifies the source line on which the editor’s 
cursor is initially placed. If you omit this parameter, the cursor is initially 
positioned at the beginning of the source line that is centered in the 
debugger’s current source display, or at the beginning of line 1 if the 
editor was set to /NOSTART_POSITION (see the SET EDITOR command 
description). 





QUALIFIERS 


/EXIT 
/NOEXIT (default) 


Controls whether you end the debugging session prior to invoking the 
editor. If you specify /EXIT, the debugging session is terminated and the 
editor is then invoked. If you specify /NOEXIT, the editing session is 
started and you return to your debugging session after terminating the 
editing session. 





DESCRIPTION 
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If you have not specified an editor with the SET EDITOR command, 
the EDIT command invokes the VAX Language-Sensitive Editor in a 
spawned subprocess (if the VAX Language-Sensitive Editor is installed 
on your system). The typical (default) way to use the EDIT command is 
not to specify any parameters. In this case, the editing cursor is initially 
positioned at the beginning of the line that is centered in the currently 
selected debugger source display (the current source display). 


The SET EDITOR command provides options for invoking different editors, 
either in a subprocess or through a callable interface. 


Related commands: (SET, SHOW) EDITOR, (SET, SHOW, CANCEL) 
SOURCE. 


EDIT 





EXAMPLES 
DBG> EDIT 


In this example, the EDIT command spawns the VAX Language-Sensitive 
Editor in a subprocess to edit the source file whose code appears in the 
current source display. The editing cursor is positioned at the beginning of 
the line that was centered in the source display. 


DBG> EDIT SWAP\12 


In this example, the EDIT command spawns the VAX Language-Sensitive 
Editor in a subprocess to edit the source file containing the module SWAP. 
The editing cursor is positioned at the beginning of source line 12. 


DBG> SET EDITOR/CALLABLE EDT 
DBG> EDIT 


In this example, the SET EDITOR/CALLABLE_EDT command establishes 
that EDT is the default editor and is invoked through its callable interface 
(rather than spawned in a subprocess). The EDIT command invokes EDT 
to edit the source file whose code appears in the current source display. 
The editing cursor is positioned at the beginning of source line 1, because 
the default qualifier /NOSTART_POSITION applies to EDT. 
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ENABLE AST 


Enables the delivery of asynchronous system traps (ASTs) in your program. 





FORMAT ENABLE AST 





DESCRIPTION = The ENABLE AST command enables the delivery of ASTs while your 
program is running, including any pending ASTs (ASTs waiting to be 
delivered). If ASTs are delivered while the debugger is running (processing 
commands, and so on), they are queued and are delivered when control is 
returned to the program. Delivery of ASTs in your program is initially 
enabled by default. 


Related commands: (DISABLE, SHOW) AST. 





EXAMPLE 


DBG> ENABLE AST 
DBG> SHOW AST 
ASTs are enabled 
DBG> 


The ENABLE AST command enables the delivery of ASTs in your 
program, as confirmed with the SHOW AST command. 
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EVALUATE 


Evaluates a language expression in the current language (by default, the 
language of the module containing the main program). 





FORMAT EVALUATE /anguage-expression[, ... ] 





PARAMETERS /anguage-expression 


Specifies any valid expression in the current language. 





QUALIFIERS /BINARY 
Specifies that the result be displayed in binary radix. 


/CONDITION_VALUE 


Specifies that the expression be interpreted as a VMS condition value (the 
kind of condition value you would specify using the condition-handling 
mechanism). The message text corresponding to that condition value is 
then displayed. The specified value must be an integer value. 


/DECIMAL 


Specifies that the result be displayed in decimal radix. 
/HEXADECIMAL 


Specifies that the result be displayed in hexadecimal radix. 


/OCTAL 
Specifies that the result be displayed in octal radix. 





DESCRIPTION The debugger interprets the expression specified in an EVALUATE 
command as a language expression, evaluates it in the syntax of the 
current language and in the current radix, and displays its value as a 
literal (for example, an integer value) in the current language. 


The current language is the language last established with the SET 
LANGUAGE command. If no SET LANGUAGE command was entered, 
the current language is, by default, the language of the module containing 
the main program. 


If an expression contains symbols with different compiler generated types, 
the debugger uses the type-conversion rules of the current language to 
evaluate the expression. 


The debugger can interpret and display integer data in any one of four 
radixes: binary, decimal, hexadecimal, and octal. The current radix is the 
radix last established with the SET RADIX command. If no SET RADIX 
command was entered, the current radix for both data entry and display 
is, by default, decimal for all languages except BLISS and MACRO. It is 
hexadecimal for BLISS and MACRO. You can use a radix qualifier with the 
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EVALUATE command (/BINARY, /OCTAL, and so on) to display integer 
data in another radix. These qualifiers do not affect how the debugger 
interprets the data you specify—that is, they override the current output 
radix, but not the input radix. 


The EVALUATE command sets the current value built-in symbols 
%CURVAL and backslash (\ ) to the value denoted by the specified 
expression. 


Debugger support for language-specific operators and constructs is 
described in Appendix E. 


Related commands: EVALUATE/ADDRESS, (SET, SHOW) LANGUAGE, 
(SET, SHOW, CANCEL) RADIX, (SET, SHOW) TYPE. 





EXAMPLES 

flo DBG> EVALUATE 100.34 * (14.2 + 7.9) 
2217.514 
DBG> 


This command uses the debugger as a calculator by multiplying 100.34 by 


(14.2 + 7.9). 
DBG> EVALUATE/OCTAL X 
00000001512 
DBG> 


This command evaluates the symbol X and displays the result in octal 
radix. 


DBG> EVALUATE TOTAL + CURR _AMOUNT 
8247.20 
DBG> 


This command evaluates the sum of the values of two real variables, 
TOTAL and CURR_AMOUNT. 


DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 

DBG> 


In this example, the EVALUATE command evaluates the logical AND of 
the current values of two Boolean variables, WILLING and ABLE. 


DBG> EVALUATE COLOR’ FIRST 
RED 
DBG> 


In this Ada example, this command evaluates the first element of the 
enumeration type COLOR. 
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EVALUATE/ADDRESS 


Evaluates an address expression and displays the result as a memory 
address or a register name. 





FORMAT EVALUATE/ADDRESS _ address-expression/, ... ] 





PARAMETERS address-expression 


Specifies an address expression of any valid form (for example, a routine 
name, a variable name, a label, a line number, and so on). 





QUALIFIERS /BINARY 


Specifies that the memory address is displayed in binary radix. 


/DECIMAL 


Specifies that the memory address is displayed in decimal radix. 


/HEXADECIMAL 


Specifies that the memory address is displayed in hexadecimal radix. 


/OCTAL 


Specifies that the memory address is displayed in octal radix. 





DESCRIPTION The EVALUATE/ADDRESS command enables you to determine the 
memory address or register associated with an address expression. 


The debugger can interpret and display integer data in any one of four 
radixes: binary, decimal, hexadecimal, and octal. The default radix for 
both data entry and display is decimal for all languages except BLISS and 
MACRO. It is hexadecimal for BLISS and MACRO. You can use a radix 
qualifier with the EVALUATE command (/BINARY, /OCTAL, and so on) 
to display address values in another radix. Note that these qualifiers do 
not affect how the debugger interprets the data you specify—that is, they 
override the current output radix, but not the input radix. 


If the value of a variable is currently stored in a register instead of 
memory, the EVALUATE/ADDRESS command identifies the register. 
The radix qualifiers have no effect in that case. | 


The EVALUATE/ADDRESS command sets the current entity built-in 
symbols %CURLOC and period (.) to the location denoted by the address 
expression specified. Logical predecessors (%PREVLOC and circumflex 
(4)) and successors (%ZNEXTLOC and pressing the Return key) are based 
on the value of the current entity. 


Related commands: EVALUATE, (SET, SHOW, CANCEL) RADIX, 
SYMBOLIZE, SHOW SYMBOL/ADDRESS. | 
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EVALUATE/ADDRESS 





EXAMPLES 

DBG> EVALUATE/ADDRESS MODNAME\%LINE 110 
3942 
DBG> 


This command displays the memory address denoted by the address 
expression MODNAME\ %LINE 110. 


DBG> EVALUATE/ADDRESS/HEX A,B,C 
000004A4 

O00004AC 

000004A0 

DBG> 


This command displays the memory addresses denoted by the address 
expressions A, B, and C in hexadecimal radix. 


DBG> EVALUATE/ADDRESS X 
MOD3\%R1 
DBG> 


This command indicates that variable X is associated with register Rl. X 
is a nonstatic (register) variable. 
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EXAMINE 


Displays the current value of a program variable. More generally, displays the 
value of the entity denoted by an address expression. 





FORMAT 


EXAMINE  /address-expression[:address-expression] 


ors || 





PARAMETERS 


address-expression 

Specifies an entity to be examined. With high-level languages, this is 
typically the name of a variable and can include a path name to specify 
the variable uniquely. More generally, an address expression can also be 
a memory address or a register and can be composed of numbers (offsets) 
and symbols, as well as one or more operators, operands, or delimiters. 
Appendix D identifies the debugger’s built-in symbols for the VAX registers 
and identifies the operators that can be used in address expressions. 


If you specify the name of an aggregate variable (a composite data 
structure such as an array or record structure) the debugger displays 
the values of all elements. For an array, the display shows the subscript 
(index) and value of each array element. For a record, the display shows 
the name and value of each record component. 


To specify an individual array element, array slice, or record component, 
use the syntax of the current language. 


If you specify a range of entities, the value of the address expression that 
denotes the first entity in the range must be less than the value of the 
address expression that denotes the last entity in the range. The debugger 
displays the entity specified by the first address expression, the logical 
successor of that address expression, the next logical successor, and so on, 
until it displays the entity specified by the last address expression. You 
can specify a list of ranges by separating ranges with a comma. 


See Chapter 11 and the descriptions of the /TMASK, /FMASK, and 
/OPERANDS qualifiers for information that is specific to vector registers 
and vector instructions. 





QUALIFIERS 


/ASCIC 

Interprets each examined entity as a counted ASCII string preceded by a 
1-byte count field that gives the length of the string. The string is then 
displayed. The /AC qualifier is also accepted. 


/ASCID 

Interprets each examined entity as the address of a string descriptor 
pointing to an ASCII string. The CLASS and DTYPE fields of the 
descriptor are not checked, but the LENGTH and POINTER fields provide 
the character length and address of the ASCII string. The string is then 
displayed. The /AD qualifier is also accepted. 
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/ASCII:n 


Interprets and displays each examined entity as an ASCII string of length 
n bytes (n characters). If n is omitted, the debugger attempts to determine 
a length from the type of the address expression. 


/ASCIW 


Interprets each examined entity as a counted ASCII string preceded by a 
2-byte count field that gives the length of the string. The string is then 
displayed. The /AW qualifier is also accepted. 


/ASCIZ 


Interprets each examined entity as a zero-terminated ASCII string. The 
ending zero byte indicates the end of the string. The string is then 
displayed. The /AZ qualifier is also accepted. 


/BINARY 


Displays each examined entity as a binary integer. 


/BYTE 
Displays each examined entity in the byte integer type (length 1 byte). 


/CONDITION_VALUE 


Interprets each examined entity as a condition-value return status and 
displays the message associated with that return status. 


/D_ FLOAT 


Displays each examined entity in the D_floating type (length 8 bytes). 
Values of type D_floating can range from .29 + 10~28 to 1.7 « 1088 with 
approximately 16 decimal digits precision. 


/DATE_TIME 


Interprets each examined entity as a quadword integer (length 8 bytes) 
containing the internal VMS representation of date and time. Displays the 
value in the format dd-mmm-yyyy hh:mmiss.xx. 


/DECIMAL 


Displays each examined entity as a decimal integer. 


/DEFAULT 


Displays each examined entity in the default radix. 


/FLOAT 


Displays each examined entity in the F_floating type (length 4 bytes). 
Values of type F_floating can range from .29 « 107° to 1.7 « 10°° with 
approximately 7 decimal digits precision. 


/FMASK[=(mask-address-expression)] 

Note: This qualifier applies to vectorized programs. 

See /TMASK. 

/G_FLOAT 

Displays each examined entity in the G_floating type (length 8 bytes). 


Values of type G_floating can range from .56 + 10728 to .9 « 10°98 with 
approximately 15 decimal digits precision. 


EXAMINE 


/H_ FLOAT 

Displays each examined entity in the H_floating type (length 16 bytes). 
Values of type H_floating can range from .84 « 10~498 to .59 « 104994 with 
approximately 33 decimal digits precision. 


/HEXADECIMAL 


Displays each examined entity as a hexadecimal integer. 


ANSTRUCTION 


Displays each examined entity as a VAX assembly-language instruction 
(variable length, depending on the number of instruction operands and the 
kind of addressing modes used). See also /OPERANDS. 


In screen mode, the output of an EXAMINE/INSTRUCTION command 
is directed at the current instruction display, if any, not at an output or 
DO display. The arrow in the instruction display points to the examined 
instruction. 


/LINE (default) 
/NOLINE 


Controls whether program locations are displayed in terms of line numbers 
(%LINE x) or as routine-name + byte-offset. By default (/LINE), the 
debugger symbolizes program locations in terms of line numbers. 


/LONGWORD 


Displays each examined entity in the longword integer type (length 4 
bytes). This is the default type for program locations that do not have a 
compiler generated type. 


/OCTAL 


Displays each examined entity as an octal integer. 


/OCTAWORD 
Displays each examined entity in the octaword integer type (length 16 
bytes). 


/OPERANDS[=keyword] 


Displays operand information associated with an examined instruction 
(displays each operand’s address and its contents, using the operand’s 
data type). The keywords BRIEF and FULL vary the amount of 
information displayed about any nonregister operands. The default is 
/OPERANDS=BRIEF. 


Use /OPERANDS only when examining the instruction at the current 
PC value (for example, EXAMINE/OPERANDS .0\%PC). Examining the 
operands of an instruction that is not at the current PC value can give 
erroneous results, because the state of the machine (the contents of the 
registers) is not set up for that instruction. 


In screen mode, operand information is directed at the current output 
display. 


When you examine the operands of a vector instruction, any operand- 
element masking that might be associated with that instruction is 
performed by default. The /T[MASK and /FMASK qualifiers enable you 

to specify some other mask. The current value of the vector length register 
(VLR) limits the highest element of a vector register that you can examine. 
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See also the SET MODE [NOJOPERANDS=keyword command. It enables 
you to set a default level for the amount of operand information displayed 
when examining instructions. 


/PACKED:n 


Interprets each examined entity as a packed decimal number. The value of 
n is the number of decimal digits. Each digit occupies one nibble (4 bits). 


/PSL 


Displays each examined entity in PSL (processor status longword) format. 


/PSW 

Displays each examined entity in PSW (processor status word) format. 
The /PSW qualifier is like /PSL except that only the low order word 

(2 bytes) is displayed. 


/QUADWORD 
Displays each examined entity in the quadword integer type (length 8 
bytes). | 


/SOURCE 


Displays the source line corresponding to the location of each examined 
entity. The examined entity must be associated with a machine code 
instruction and, therefore, must be a line number,.a label, a routine name, 
or the memory address of an instruction. The examined entity cannot be 
a variable name or any other address expression that is associated with 
data. 


In screen mode, the output of an EXAMINE/SOURCE command is directed 
at the current source display, if any, not at an output or DO display. The 
arrow in the source display points to the source line associated with the 
last entity specified (or the last one specified in a list of entities). 


/SYMBOLIC (default) 


/NOSYMBOLIC 

Controls whetker symbolization occurs. By default (SYMBOLIC), 

the debugger symbolizes all addresses, if possible; that is, it converts 
numeric addresses into their symbolic representation. If you specify 
/NOSYMBOLIC, the debugger suppresses symbolization of entities you 
specify as absolute addresses. If you specify entities as variable names, 
symbolization still occurs. The /NOSYMBOLIC qualifier is useful if you 
are interested in identifying numeric addresses rather than their symbolic 
names (if symbolic names exist for those addresses). If you specify 
/NOSYMBOLIC, command processing might speed up somewhat, because 
the debugger does not need to convert numbers to names. 


/TASK 
Note: This qualifier applies to Ada programs. 


Interprets each examined entity as an Ada task object and displays the 
task value (the name or task ID) of that task object. 


/TMASK[=(mask-address-expression)] 
/FMASK[=(mask-address-expression)] 


Note: These qualifiers apply to vectorized programs. 


EXAMINE 


These qualifiers enable you to specify a mask in order to display certain 
elements of a vector register (VO to V15), or of an array in memory, while 
not displaying other elements. 


For example, when you examine the operands of a vector instruction 
(by using the /OPERANDS qualifier), these qualifiers enable you to 
override any operand-element masking that might be associated with 
that instruction. 


The /TMASK qualifier applies the EXAMINE command only to the 
elements of the register or array that correspond to the set bits (bit value: 
1) of the mask. The /FMASK qualifier applies the EXAMINE command 
only to the elements that correspond to the clear bits (bit value: 0) of the 
mask. The current value of the vector length register (VLR) limits the 
highest register element that you can examine but not the highest array 
element. 


By default, if you do not specify a mask address expression with /TMASK 
or /FMASK, the vector mask register (VMR) is used. That is, the 
EXAMINE command is applied only to the elements of the vector register 
or array that correspond to the set bits (in the case of /TMASK) or clear 
bits Gin the case of /FMASK) of VMR. 


If you specify a mask address expression with /TMASK or /FMASK, 
the value at that address is used as the mask, subject to the following 
conventions: | 


¢ You must use parentheses around the address expression. 


¢ The number of mask elements limits the number of register or array 
elements that you can examine. 


e Ifthe mask address expression denotes a Boolean array, its values 
are used as the mask, in the same basic way that VMR is used in the 
default case. 


e Ifthe mask address expression denotes a non-Boolean array, the least 
significant bit value of each array element is used as the mask for the 
corresponding element of the register or target array. 


e Ifthe mask address expression denotes a Boolean scalar type, its value 
is used as the mask for the first element of the register or target array. 
No other elements are examined. 


e If the mask address expression denotes any other type, its least 
significant bit value is used as the mask for the first element of the 
register or target array. No other elements are examined. 


e For a multi-element mask, the lowest specified element of the mask is 
applied to the lowest specified element of the register or target array. 


/TYPE=(type-expression) 

Interprets and displays each examined entity according to the type 
specified by type-expression (the name of a variable or data type declared 
in the program). This enables you to specify a user-declared type. 


/WORD 
Displays each examined entity in the word integer type (length 2 bytes). 
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DESCRIPTIO 
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The EXAMINE command displays the entity at the location denoted by an 
address expression. The command can be used to display the contents of 
any memory location or register that is accessible in your program. For 
high-level languages the command is used mostly to obtain the current 
value of a variable (an integer, real, string, array, record, and so on). 


The debugger recognizes the compiler generated types associated with 
symbolic address expressions (symbolic names declared in your program). 
Symbolic address expressions include the following entities: 


e Variable names. When specifying a variable with the EXAMINE 
command, use the same syntax that is used in the source code. 


¢ Routine names, labels, and line numbers. These are associated with 
VAX instructions. You can examine instructions using the same 
techniques as when examining variables. 


In general, when you enter an EXAMINE command, the debugger 
evaluates the address expression specified to yield a program location. 
The debugger then displays the value stored at that location as follows: 


e Ifthe location has a symbolic name, the debugger formats the value 
according to the compiler generated type associated with that symbol— 
that is, as a variable of a particular type or as a VAX instruction. 


e Ifthe location does not have a symbolic name (and, therefore, no 
associated compiler generated type) the debugger formats the value 
in the type longword integer by default. This means that, by default, 
the EXAMINE command displays the contents of these locations as 
longword (4-byte) integer values. 


See Chapter 11 and the descriptions of the /TMASK, /FMASK, and 
/OPERANDS qualifiers for information that is specific to vector registers 
and vector instructions. 


There are several ways of changing the type associated with a program 
location so that you can display the data at that location in another data 
format: 


¢ To change the default type for all locations that do not have a symbolic 
name, you can specify a new type with the SET TYPE command. 


¢ To change the default type for all locations (both those that do and do 
not have a symbolic name), you can specify a new type with the SET 
TYPE/OVERRIDE command. 


¢ To override the type currently associated with a particular location 
for the duration of a single EXAMINE command, you can specify a 
new type by means of a type qualifier (/ASCII:n, /BYTE, /TYPE=(type- 
expression), and so on). Most of the EXAMINE command qualifiers are 
type qualifiers. 


The debugger can interpret and display integer data in any one of four 
radixes: binary, decimal, hexadecimal, and octal. The default radix 
for both data entry and display is decimal for all languages except 
BLISS and MACRO. It is hexadecimal for BLISS and MACRO. The 
EXAMINE command has four radix qualifiers (/BINARY, /DECIMAL, 


EXAMINE 


/HEXADECIMAL, /OCTAL) that enable you to display data in another 
radix. You can also use the SET RADIX and SET RADIX/OVERRIDE 
commands to change the default radix. 


In addition to the type and radix qualifiers, the EXAMINE command has 
qualifiers for other purposes: 


e The /SOURCE qualifier enables you to identify the line of source code 
corresponding to a line number, routine name, label, or any other 
address expression that is associated with an instruction rather than 
data. 


e The /[NOJLINE and /[NO]JSYMBOL qualifiers enable you to control the 
symbolization of address expressions. 


The EXAMINE command sets the current entity built-in symbols 
%CURLOC and period (.) to the location denoted by the address 
expression specified. Logical predecessors (HZPREVLOC and circumflex 
(“)) and successors (%NEXTLOC and pressing the Return key) are based 
on the value of the current entity. 


Related Commands: DEPOSIT, EVALUATE, (SET, SHOW, CANCEL) 
RADIX, (SET, SHOW) TYPE, CANCEL TYPE/OVERRIDE, SET MODE 
[NOJOPERANDS, SET MODE [NO]SYMBOLIC. 





EXAMPLES 


DBG> EXAMINE COUNT 
SUB2\COUNT: 27 
DBG> 


This command displays the value of the integer variable COUNT, in 
module SUB2. 


DBG> EXAMINE PART NUMBER 
INVENTORY\PART NUMBER: "LP-3592.6-84" 
DBG> : 
This command displays the value of the string variable PART_NUMBER. 


DBG> EXAMINE SUB1\ARR3 


SUB1\ARR3 
Clg irs 27.01000 
(1,2): 31.01000 
(ies) 12.48000 
(2,1): 15.08000 
(27-2);% 22.30000 
(2,3): 18.73000 

DBG> 


This command displays the value of all elements in array ARR3, in module 
SUB1. ARR3 is a 2 by 3 element array of real numbers. 
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DBG> EXAMINE SUB1\ARR3 (2,1:3) 


SUB1\ARR3 
(2,1): 15.08000 
(2,2)% 22.30000 
(2,3): 18.73000 
DBG> 


This command displays the value of the elements in a slice of array 
SUB1\ ARR3. The slice includes "columns" 1 to 3 of "row" 2. 


DBG> EXAMINE VALVES.INTAKE.STATUS 
MONITOR\VALVES.INTAKE.STATUS: OFF 
DBG> 


This command displays the value of the nested record component 
VALVES.INTAKE.STATUS in module MONITOR. 


DBG> EXAMINE/SOURCE SWAP 
module MAIN 
47: procedure SWAP (X,Y: in out INTEGER) is 


DBG> 
This command displays the source line in which routine SWAP is declared 
(the location of routine SWAP). 

DBG> DEPOSIT/ASCII:7 WORK+20 = ’abcdefg’ 

DBG> EXAMINE/ASCII:7 WORK+20 

DETAT\WORK+20: "abcdefg" 

DBG> EXAMINE/ASCII:5 WORK+20 

DETAT\WORK+20: "abcde" 

DBG> 


In this example, the DEPOSIT command deposits the entity ‘abcdefg’ as 
an ASCII string of length 7 bytes into the location that is 20 bytes beyond 
the location denoted by the symbol WORK. The first EXAMINE command 
displays the value of the entity at that location as an ASCII string of 
length 7 bytes (abcdefg). The second EXAMINE command displays the 
value of the entity at that location as an ASCII string of length 5 bytes 
(abcde). 


DBG> EXAMINE/INST MAIN+2 
MAIN\MAIN+02: MOVAL L*MAINA, R11 
DBG> 


This command displays the contents of the location that is 2 bytes beyond 
the location denoted by the symbol MAIN as an instruction (MOVAL). 


DBG> EXAMINE/OPERANDS=FULL .O\%PC 
X\XSSTART+0C: MOVL B*04 (R4),R7 
B*04 (R4) R4 contains X\XSSTART\M (address 00001054), 
B*04 (00001054) evaluates to X\XSSTART\K 
(address 00001058), which contains 00000016 
RR? R7 contains 00000000 
DBG> 


This command displays the instruction (MOVL) at the current PC value. 
The /OPERANDS qualifier with the keyword FULL displays the maximum 
level of operand information. 
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DBG> SET RADIX HEXADECIMAL 

DBG> EVALUATE/ADDRESS WORKDATA 
O000086F 

DBG> EXAMINE/SYMBOLIC 0000086F 
MOD3\WORKDATA: 03020100 

DBG> EXAMINE/NOSYMBOLIC O000086F 
OOO00086F: 03020100 

DBG> 


In this example, the EVALUATE/ADDRESS command indicates that the 
memory address of variable WORKDATA is 0000086F, hexadecimal. The 
two EXAMINE commands display the value contained at that address 
using the /[NO]JSYMBOL qualifier to control whether the address is 
symbolized to WORKDATA. 


DBG> EXAMINE/HEX FIDBLK 
FDEX1SMAIN\FIDBLK 
(1): 00000008 
(2): 00000100 
cS)i% OO0000AB 
DBG> 


This command displays the value of the array variable FIDBLK in 
hexadecimal radix. 


DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6 
SUB2\NEWDATA: 256 

SUB2\NEWDATA+2: 770 

SUB2\NEWDATA+4: 1284 

SUB2\NEWDATA+6: 1798 

DBG> 


This command displays, in decimal radix, the values of word integer 
entities (2-byte entities) that are in the range of locations denoted by 
NEWDATA to NEWDATA + 6 bytes. 

DBG> EXAMINE/TASK ALPHA 

SAMPLE.ALPHA: %TASK 2 

DBG> 


This command interprets ALPHA to be the address of an Ada task object 
and displays the task value TASK 2 associated with that task object. 
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EXIT 


Ends a debugging session, or terminates one or more processes of a 
multiprocess program, allowing any application-declared exit handlers to 
run. 


lf used within a command procedure or DO clause and no process is 
specified, exits the command procedure or DO clause at that point. 





FORMAT 


EXIT /process-specf, ... |] 





PARAMETERS 
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pr ocess-Spec 

Note: This parameter applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


Specifies a process. Use any of the following forms: 


[%¥PROCESS_NAME] process-name The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

[%PROCESS_NAME] "process-name" The VMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number (or The number assigned to a process 


%PROC process-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 


/PROCESS_GROUP command to 
represent a group of processes. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 

%PREVIOUS_PROCESS The process previous to the visible 
process in the debugger’s circular 
process list. 

%VISIBLE_PROCESS The process whose cail stack, register 


set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk wildcard character (*) to specify all 
processes. 


EXIT 





DESCRIPTION 


The EXIT command is one of the four debugger commands that can be 
used to execute your program (the others are CALL, GO, and STEP). 


Ending a Debugging Session 


To end a debugging session, enter the EXIT command at the debugger 
prompt without specifying any parameters. This causes orderly 
termination of the session: the program’s application-declared exit 
handlers (if any) are executed, the debugger exit handler is executed 
(closing log files, restoring the screen and keypad states, and so on), 

and control is returned to the command interpreter. You cannot then 
continue to debug your program by entering the DCL commands DEBUG 
or CONTINUE. To restart the debugger, you must run the program again. 


Note that, since EXIT runs any application-declared exit handlers, you can 
set breakpoints in such exit handlers, and the breakpoints are triggered 
upon typing EXIT. EXIT can thus be used to debug your exit handlers. 


To end a debugging session without running any application-declared exit 
handlers, use the QUIT command instead of EXIT. 


Using the EXIT Command in Command Procedures and DO Clauses 


When the debugger executes an EXIT command (without any parameters) 
in a command procedure, control returns to the command stream that 
invoked the command procedure. A command stream can be the terminal, 
an outer (containing) command procedure, or a DO clause in a command 
or screen display definition. For example, if the command procedure was © 
invoked from within a DO clause, control returns to that DO clause, where 
the debugger executes the next command (if any remain in the command 
sequence). 


When the debugger executes an EXIT command (without any parameters) 
in a DO clause, it ignores any remaining commands in that clause and 
displays its prompt. 


Terminating Specified Processes 


If you are using the multiprocess debugging configuration to debug a 
multiprocess program (if the logical name DBG$PROCESS has the value 
MULTIPROCESS), you can use the EXIT command to terminate specified 
processes without ending the debugging session. The same techniques and 
behavior apply, whether you enter the EXIT command at the prompt or 
use it within a command procedure or DO clause. 


To terminate one or more processes, enter the EXIT command, specifying 
these processes as parameters. This causes orderly termination of the 
images in these processes, executing any application-declared exit handlers 
associated with these images. Subsequently, the specified processes are no 
longer identified in a SHOW PROCESS/ALL display. If any specified 
processes were on hold, as the result of a SET PROCESS/HOLD command, 
the hold condition is ignored. 
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When the specified processes begin to exit, any unspecified process that 
is not on hold begins execution. After execution is started, the way 

in which it continues depends on whether the command SET MODE 
[NOJINTERRUPT was entered previously. By default (SET MODE 
INTERRUPT), execution continues until it is suspended in any process. 
At that point, execution is interrupted in any other processes that were 
executing images, and the debugger prompts for input. 


To terminate specified processes without running any application-declared 
exit handlers or otherwise starting execution, use the QUIT command 
instead of EXIT. 


Related commands: CTRL/Z, QUIT, CTRL/C, SET ABORT_KEY, CTRL/Y, 
@file-spec, SET PROCESS, SET MODE [NO]JINTERRUPT. 





EXAMPLES 
DBG> EXIT 
$ 


This command ends the debugging session and returns you to DCL 
command level. 


JONES 1> EXIT %NEXT PROCESS, %PROCESS NAME JONES 3, %PROC 5 
JONES 1> 


This command causes orderly termination of three processes of a 
multiprocess program: the process after the visible process on the process 
list, process JONES_8, and process 5. Control is returned to the debugger 
after the specified processes have exited. 
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EXITLOOP 


Exits one or more enclosing FOR, REPEAT, or WHILE loops. 





FORMAT EXITLOOP [n/ 


PARAMETERS "1 


A decimal integer that specifies the number of nested loops to exit from. 
The default is 1. 








DESCRIPTION — Use the EXITLOOP command to exit one or more enclosing FOR, REPEAT, 
or WHILE loops. 


Related commands: FOR, REPEAT, WHILE. 





EXAMPLE 


DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP) 


The WHILE 1 command generates an endless loop that executes a STEP 
command with each iteration. After each STEP, the value of X is tested. 
If X is greater than 3, the EXITLOOP command terminates the loop 
(FORTRAN example). 
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EXPAND 


Expands or contracts the window associated with a screen display. 











FORMAT EXPAND [disp-namef, ... |] 

PARAMETERS disp-name 
Specifies a display to be expanded or contracted. You can specify any of 
the following entities: 
e A predefined display: SRC, OUT, PROMPT, INST, REG 
e Adisplay previously created with the DISPLAY command 
e Adisplay built-in symbol: %CURDISP, 2CURSCROLL, 2NEXTDISP, 

%NEXTINST, ZNEXTOUTPUT, ZNEXTSCROLL, ZNEXTSOURCE 

If you do not specify a display, the current scrolling display, as established 
by the SELECT command, is chosen. 
You must specify at least one qualifier. 

QUALIFIERS /DOWN{:n] 
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Moves the bottom border of the display down by n lines (if n is positive) or 
up by 7 lines (ifn is negative). If n is omitted, the border is moved down 
by 1 line. 


/LEFT[:n] 

Moves the left border of the display to the left by n lines (if n is positive) 
or to the right by n lines (if n is negative). If n is omitted, the border is 
moved to the left by 1 line. 


/RIGHT[:n] 


Moves the right border of the display to the right by n lines (if n is 
positive) or to the left by n lines (if n is negative). If n is omitted, the 
border is moved to the right by 1 line. 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 


or key definitions that are bound to display definitions. 


EXPAND 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 


/UPI[:n] 

Moves the top border of the display up by 7 lines (if n is positive) or down 
by n lines (if n is negative). If n is omitted, the border is moved up by 1 
line. 





DESCRIPTION The EXPAND command moves one or more display-window borders 
according to the qualifiers specified (/UP:[n], /DOWN:{n], RIGHT:[n], 
/LEFT:[n])). 


The EXPAND command does not affect the order of a display on the 
display pasteboard. Depending on the relative order of displays, the 
EXPAND command can cause the specified display to hide or uncover 
another display or be hidden by another display, partially or totally. 


Except for the PROMPT display, any display can be contracted to the 
point where it disappears (at which point it is marked as "removed"). It 
can then be expanded from that point. Contracting a display to the point 
where it disappears causes it to lose any attributes that were selected for 
it. The PROMPT display cannot be contracted or expanded horizontally 
but can be contracted vertically to a height of 2 lines. 


A window border can be expanded only up to the edge of the screen. The 
left and top window borders cannot be expanded beyond the left and top 
edges of the display, respectively. The right border can be expanded up 
to 255 columns from the left display edge. The bottom border of a source 
or instruction display can be expanded down only to the bottom edge of 
the display (to the end of the source module or routine’s instructions). A 
register display cannot be expanded beyond its full size. 


See Appendix B for keypad-key definitions associated with the EXPAND 
command. 


Related commands: MOVE, DISPLAY, SELECT/SCROLL, (SET, SHOW) 
TERMINAL. 





EXAMPLES 


DBG> EXPAND/RIGHT: 6 


This command moves the right border of the current scrolling display to 
the right by 6 columns. 
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DBG> EXPAND/UP/RIGHT:-12 OUT2 


This command moves the top border of display OUT2 up by 1 line, and the 
right border to the left by 12 columns. 


DBG> EXPAND/DOWN:99 SRC 


This command moves the bottom border of display SRC down to the 
bottom edge of the screen. 


CD-100 


EXTRACT 


EXTRACT 


Saves the contents of screen displays in a file or creates a debugger 
command procedure with all of the commands necessary to recreate the 
current screen state at a later time. 





FORMAT 


EXTRACT /[disp-namef, ... |] [file-spec] 





PARAMETERS 


disp-name 

Specifies a display to be extracted. You can specify any of the following 
entities: 

¢ A predefined display: SRC, OUT, PROMPT, INST, REG 


e Adisplay previously created with the DISPLAY command 


You can use the asterisk wildcard character (*) in a display name. Do not 
specify a display name with /ALL. 


file-spec 
Specifies the file to which the information is written. You can specify a 
logical name. 


If you specify /SCREEN_LAYOUT, the default specification for the file is 
SYS$DISK:[ JDBGSCREEN.COM. Otherwise, the default specification is 
SYS$DISK:[ JDEBUG. TXT. 





QUALIFIERS 


/ALL 


Extracts all displays. Do not specify a display name with /ALL. Do not 
specify /SCREEN_LAYOUT with /ALL. 


/APPEND 

Appends the information at the end of the file, rather than creating a new 
file. By default, a new file is created. Do not specify /SCREEN_LAYOUT 
with /APPEND. 


/SCREEN_LAYOUT 


Writes a file that contains the debugger commands describing the current 
state of the screen. This information includes the screen height and width, 
and the position, display kind, and display attributes of every existing 
display. This file can then be executed with the @file-spec command to 
reconstruct the screen at a later time. 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 
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Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS _ NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS _PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 





DESCRIPTION 


When you use the EXTRACT command to save the contents of a display 
into a file, only those lines that are currently stored in the display’s 
memory buffer (as determined by the /SIZE qualifier on the DISPLAY 
command) are written to the file. 


You cannot extract the PROMPT display into a file. 
Related commands: SAVE, DISPLAY. 





EXAMPLES 


DBG> EXTRACT SRC 


| 


|G | 
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This command writes all the lines in display SRC into file 
SYS$DISK:[ JDEBUG.TXT. 


DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE 


This command appends all the lines in display OUT to the end of file 
[JONES.WORKIMYFILE.TXT. 


DBG> EXTRACT/SCREEN LAYOUT 


This command writes the debugger commands needed to reconstruct the 


screen into file SYS$DISK:[ JDBGSCREEN.COM. 


FOR 


FOR 


Executes a sequence of commands while incrementing a variable a specified 
number of times. 





FORMAT 


FOR name=expressioni TO expression2 [BY 
expression3] DO (command; .. . ]) 





PARAMETERS 


name 


Specifies the name of a count variable. 


expression! 
Specifies an integer or enumeration type value. The expression1 and 
expression2 parameters must always be of the same type. 


expression2 
Specifies an integer or enumeration type value. The expression1 and 
expression2 parameters must always be of the same type. 


expression3 


Specifies an integer. 


command 
Specifies a debugger command. If you specify more than one command, 
they must be separated by semicolons. 





DESCRIPTION 


The behavior of the FOR command depends on the value of the expression3 
parameter. If expression3 is positive, name is incremented from the value 
of expression1 by the value of expression3 until it is greater than the value 
of expression2. 


If expression’ is negative, name is decremented from the value of 
expression1 by the value of expression’ until it is less than the value of 
expression2. 


If expression’ is zero, the debugger returns an error message. 


If expression8 is left out entirely, the debugger assumes it to have the 
value +1. 


Related commands: REPEAT, WHILE, EXITLOOP. 
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EXAMPLES 


DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(TI)) 


This command examines an array backwards. 


DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 


This command initializes an array to zero. 
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Starts or resumes program execution. 





FORMAT 


GO __[address-expression] 





PARAMETERS 


address-expression 

Specifies that program execution resume at the location denoted by the 
address expression. If you do not specify an address expression, execution 
resumes at the point of suspension or, in the case of debugger start up, at 
the image transfer address. 





DESCRIPTION 


The GO command starts program execution or resumes execution from the 
point at which it is currently suspended. GO is one of the four debugger 
commands that can be used to execute your program (the others are CALL, 
EXIT, and STEP). 


Note that specifying an address expression with the GO command can 
produce unexpected results because it alters the normal control flow of 
your program. For example, during a debugging session you can restart 
execution at the beginning of the program by entering the command GO 
%LINE 1. However, because the program has executed, the contents of 
some variables might now be initialized differently from when you first 
ran the program. 


If an exception breakpoint is triggered (resulting from a SET BREAK 
/EXCEPTION or a STEP/EXCEPTION command), execution is suspended 
before any application-declared condition handler is invoked. If you then 
resume execution with the GO command, the behavior is as follows: 


e Entering a GO command to resume execution from the current location 
causes the debugger to resignal the exception. This use of the GO 
command enables you to observe which application-declared handler, if 
any, next handles the exception. 


e Entering a GO command to resume execution from a location other 
than the current location inhibits the execution of any application- 
declared handler for that exception. 


If you are using the multiprocess debugging configuration to debug a 
multiprocess program (if the logical name DBG$PROCESS has the value 
MULTIPROCESS), note the following additional points: 


¢ The GO command is executed in the context of the visible process, 
but images in any other processes that are not on hold (through a SET 
PROCESS/HOLD command) are also allowed to execute. If you use the 
DO command to broadcast a GO command to one or more processes, 
the GO command is executed in the context of each specified process 
that is not on hold, but images in any other processes that are not on 
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hold are also allowed to execute. In all cases, a hold condition in the 
visible process is ignored. 


e After execution is started, the way in which it continues depends on 
whether the command SET MODE [NOJINTERRUPT was entered. 
By default (SET MODE INTERRUPT), execution continues until it 
is suspended in any process. At that point, execution is interrupted 
in any other processes that were executing images, and the debugger 
prompts for input. 


Related commands: STEP, SET STEP, SET BREAK, SET TRACE, 
SET WATCH, CALL, EXIT, DO, SET PROCESS, SET MODE 
[LNOJINTERRUPT. 





EXAMPLES 


DBG> GO 


SDEBUG-I-EXITSTATUS, is ’%SYSTEM-S-NORMAL, normal successful 
completion’ 
DBG> 


This command starts program execution, which then completes 
successfully. 


DBG> SET BREAK RESTORE 
DBG> GO 


break at routine INVENTORY\RESTORE 
137: procedure RESTORE; 
DBG> GO 


DBG> 


This SET BREAK command sets a breakpoint on routine RESTORE. The 
first GO command starts program execution, which is then suspended at 
the breakpoint on routine RESTORE. The second GO command resumes 
execution from the breakpoint. 


DBG> GO %LINE 42 


This command resumes program execution at line 42 of the module in 
which execution is currently suspended. 
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HELP 


Displays online help on debugger commands and selected topics. 





FORMAT 


HELP help-topic[subtopic[... ]] 





PARAMETERS 


help-topic 
Specifies the name of a debugger command or topic about which you need 
help. You can specify the asterisk wildcard character (*), either singly or 
within a name. 


subtopic 

Specifies a subtopic, command qualifier, or command parameter about 
which you want further information. You can specify *, either singly or 
within a name. 





DESCRIPTION 


The debugger’s online help facility provides the following information 
about any debugger command: a description of the command, format of 
the command, parameters that can be specified with the command, and 
qualifiers that can be specified with the command. 


To obtain information about a particular qualifier or parameter, specify 
it as a subtopic. If you want information about all command qualifiers, 
specify "qualifier" as a subtopic. If you want information about all 
parameters, specify "parameter" as a subtopic. If you want information 
about all parameters, qualifiers, and any other subtopics related to a 
command, specify * as a subtopic. 


In addition to help on commands, you can get online help on various topics 
such as screen features, keypad mode, and so on. Topic keywords are 
listed along with the commands when you type HELP. 


Type HELP Release_Notes for information about any incompatibilities 
between the current release of the debugger and previous releases. Type 
HELP New_Features for summary information about new features with 
this release of the debugger. 


For help on the predefined keypad-key functions, see Appendix B. 





EXAMPLE 


DBG> HELP GO 
GO 


The GO command starts program execution or resumes execution 
from the point at which it is currently suspended. GO is one 
of the four debugger commands that can be used to execute 
your program (the others are CALL, EXIT, and STEP). 
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HELP 


Note that specifying an address expression with the GO 
command can produce unexpected results because it alters the 
normal control flow of your program. For example, during a 
debugging session you can restart execution at the beginning 
of the program by entering the command GO SLINE 1. However, 
because the program has executed, the contents of some 
variables might now be initialized differently from when you 
first ran the program. 


Format: 
GO [address-expression] 
Additional information available: 


Examples Multiprocess Programs Parameters 


This command displays help for the GO command. 
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IF 


Executes a sequence of commands if a language expression (Boolean 
expression) is evaluated as true. 





FORMAT IF Boolean-expression THEN (command; ... ]) 
[ELSE (command; ... ])] 





PARAMETERS’ Boolean-expression 
Specifies a language expression that evaluates as a Boolean value (true or 
false) in the currently set language. 


command 
Specifies a debugger command. If you specify more than one command, 
you must separate them with semicolons (;). 





DESCRIPTION The IF command evaluates a Boolean expression. If the value is true (as 
defined in the current language), the debugger command list in the THEN 
clause is executed. If the expression is false, the command list in the 
ELSE clause is executed (if it is present). 


Related commands: FOR, REPEAT, WHILE, EXITLOOP. 





EXAMPLE 


DBG> SET BREAK R DO (IF X .LT.5 THEN (GO) ELSE (EXAMINE X)) 


This command causes the debugger to suspend program execution at 
location R (a breakpoint) and then resume program execution if the value 
of X is less than 5 (FORTRAN example). If the value of X is 5 or more, the 


value of X is displayed. 
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MOVE 


Moves a screen display vertically or horizontally across the screen. 





FORMAT 


MOVE /disp-namef, ... ]] 





PARAMETERS 


disp-name 
Specifies a display to be moved. You can specify any of the following 
entities: 


e A predefined display: SRC, OUT, PROMPT, INST, REG 
¢ Adisplay previously created with the DISPLAY command 


e A display built-in symbol: %CURDISP, %CURSCROLL, %NEXTDISP, 
YNEXTINST, SZNEXTOUTPUT, %ZNEXTSCROLL, SNEXTSOURCE 


If you do not specify a display, the current scrolling display, as established 
by the SELECT command, is chosen. 


You must specify at least one qualifier. 





QUALIFIERS 
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/DOWNI:n] 
Moves the display down by n lines (if n is positive) or up by 7 lines (if 7 is 
negative). If n is omitted, the display is moved down by 1 line. 


/LEFTI:n] 
Moves the display to the left by n lines Gif n is positive) or right by n lines 
(if n is negative). If n is omitted, the display is moved to the left by 1 line. 


/RIGHTI:n] 

Moves the display to the right by n lines (if n is positive) or left by n lines 
(if n is negative). If n is omitted, the display is moved to the right by 1 
line. 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 
PROCESS_NAME The display-name suffix is the VMS process name. 


MOVE 


PROCESS_NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 


/UPI[:n] 
Moves the display up by n lines (if n is positive) or down by n lines (if n is 
negative). If n is omitted, the display is moved up by 1 line. 





DESCRIPTION 


For each display specified, the MOVE command simply creates a window 
of the same dimensions elsewhere on the screen and maps the display to 
it, while maintaining the relative position of the text within the window. 


The MOVE command does not change the order of a display on the display 
pasteboard. Depending on the relative order of displays, the MOVE 
command can cause the display to hide or uncover another display or 

be hidden by another display, partially or totally. 


A display can be moved only up to the edge of the screen. 


See Appendix B for keypad-key definitions associated with the MOVE 
command. 


Related commands: EXPAND, DISPLAY, SELECT/SCROLL, (SET, SHOW) 
TERMINAL. 





EXAMPLES 


DBG> MOVE/LEFT 


This command moves the current scrolling display to the left by 1 column. 


DBG> MOVE/UP:3/RIGHT:5 NEW OUT 


This command moves display NEW_OUT up by 38 lines and to the right by 
5 columns. 
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QUIT 


Ends a debugging session, or terminates one or more processes of a 
multiprocess program (like EXIT), but without allowing any application- 
declared exit handlers to run. 


lf used within a command procedure or DO clause and no process is 
specified, exits the command procedure or DO clause at that point. 





FORMAT 


QUIT [process-spec/, ... ]] 





PARAMETERS 
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process-spec 

Note: This parameter applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


Specifies a process. Use any of the following forms: 


[%~PROCESS NAME] process-name The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

[%~PROCESS_NAME] "process-name" The VMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number (or The number assigned to a process 


%PROC process-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 


/PROCESS_GROUP command to 
represent a group of processes. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 

%PREVIOUS_PROCESS The process previous to the visible 
process in the debugger’s circular 
process list. 

%VISIBLE_PROCESS The process whose call stack, register 


set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk wildcard character (*) to specify all 
processes. 


QUIT 





DESCRIPTION 


The QUIT command is like the EXIT command, except that QUIT does 
not cause your program to execute and, therefore, does not execute any 
application-declared exit handlers in your program. 


Ending a Debugging Session 


To end a debugging session, enter the QUIT command at the debugger 
prompt without specifying any parameters. This causes orderly 
termination of the session: the debugger exit handler is executed (closing 
log files, restoring the screen and keypad states, and so on), and control is 
returned to the command interpreter. You cannot then continue to debug 
your program by entering the DCL commands DEBUG or CONTINUE. To 
restart the debugger, you must run the program again. 


Using the QUIT Command in Command Procedures and DO Clauses 


When the debugger executes a QUIT command (without any parameters) 
in a command procedure, control returns to the command stream that 
invoked the command procedure. A command stream can be the terminal, 
an outer (containing) command procedure, or a DO clause in a command 
or screen display definition. For example, if the command procedure was 
invoked from within a DO clause, control returns to that DO clause, where 
the debugger executes the next command (if any remain in the command 
sequence). 


When the debugger executes a QUIT command (without any parameters) 
in a DO clause, it ignores any remaining commands in that clause and 
displays its prompt. 


Terminating Specified Processes 


If you are using the multiprocess debugging configuration to debug a 
multiprocess program (if the logical name DBG$PROCESS has the value 
MULTIPROCESS), you can use the QUIT command to terminate specified 
processes without ending the debugging session. The same techniques and 
behavior apply, whether you enter the QUIT command at the prompt or 
use it within a command procedure or DO clause. 


To terminate one or more processes, enter the QUIT command, specifying 
these processes as parameters. This causes orderly termination of the 
images in these processes without executing any application-declared 
exit handlers associated with these images. Subsequently, the specified 
processes are no longer identified in a SHOW PROCESS/ALL display. 


In contrast to the EXIT command, the QUIT command does not cause any 
process to start execution. 


Related commands: EXIT, CTRL/Z, CTRL/C, SET ABORT_KEY, CTRL/Y, 
@file-spec, SET PROCESS. 
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QUIT 





EXAMPLES 


DBG> QUIT 
$ 


This command, when entered from the prompt, ends the debugging session 
and returns you to DCL command level. 


JONES _1> QUIT %NEXT PROCESS, %PROCESS NAME JONES 3, %PROC 5 
JONES _1> 


This command causes orderly termination of three processes of a 
multiprocess program: the process after the visible process on the process 
list, process JONES_3, and process 5. Control is returned to the debugger 
after the specified processes have exited. 
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REPEAT 


Executes a sequence of commands a specified number of times. 





FORMAT REPEAT /ang-expDO (command; ... ]) 





PARAMETERS _/ang-exp 


Denotes any expression in the currently set language that evaluates to a 
positive integer. 


command 


Specifies a debugger command. If you specify more than one command, 
they must be separated by semicolons. 





DESCRIPTION The REPEAT command is a simple form of the FOR command. The 
EPEAT command executes a sequence of commands repetitively a 
specified number of times, without providing the options for establishing 
count parameters that the FOR command does. 


Related commands: FOR, WHILE, EXITLOOP. 





EXAMPLE 


DBG> REPEAT 10 DO (EXAMINE Y; STEP) 


This command line sets up a loop that issues a sequence of two commands 
(EXAMINE Y then STEP) 10 times. 
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SAVE 


Preserves the contents of an existing screen display in a new display. 





FORMAT 


SAVE  old-disp AS new-disp[, ... ] 





PARAMETERS 


old-disp 
Specifies the display whose contents are saved. You can specify any of the 
following entities: 


e A predefined display: SRC, OUT, PROMPT, INST, REG 
e A display previously created with the DISPLAY command 


¢ A display built-in symbol: ZCURDISP, S2CURSCROLL, %2NEXTDISP, 
%NEXTINST, SZNEXTOUTPUT, ZNEXTSCROLL, 2ZNEXTSOURCE 


new-disp 
Specifies the name of the new display to be created. This new display then 
receives the contents of the old-disp display. 





QUALIFIERS 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 





DESCRIPTION 
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The SAVE command enables you to save a "snapshot" copy of an existing 
isplay in a new display for later reference. The new display is created 
with the same text contents as the existing display. In general, the new 
display is given all the attributes or characteristics of the old display 
except that it is removed from the screen and is never automatically 


SAVE 


updated. You can later recall the saved display to the terminal screen with 
the DISPLAY command. 


When you use the SAVE command, only those lines that are currently 
stored in the display’s memory buffer (as determined by the /SIZE qualifier 
on the DISPLAY command) are stored in the saved display. However, in 
the case of a saved source or instruction display, you can also see any 
other source lines associated with that module or any other instructions 
associated with that routine (by scrolling the saved display). 


You cannot save the PROMPT display. 
Related commands: EXTRACT, DISPLAY. 





EXAMPLE 


DBG> SAVE REG AS OLDREG 


This command saves the contents of the display named REG into the 
newly created display named OLDREG. 
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SCROLL 


Scrolls a screen display to make other parts of the text visible through the 
display window. 





FORMAT 


SCROLL [disp-name] 





PARAMETERS 


disp-name 
Specifies a display to be scrolled. You can specify any of the following 
entities: 


e A predefined display: SRC, OUT, PROMPT, INST, REG 
e A display previously created with the DISPLAY command 


e A display built-in symbol: %CURDISP, %CURSCROLL, %NEXTDISP, 
JNEXTINST, SNEXTOUTPUT, ZNEXTSCROLL, ZNEXTSOURCE 


If you do not specify a display, the current scrolling display, as established 
by the SELECT command, is chosen. 





QUALIFIERS 
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/BOTTOM 


Scrolls down to the bottom of the display’s text. 
/DOWN:[n] 


Scrolls down over the display’s text by n lines to reveal text further down 
in the display. If n is omitted, the display is scrolled by approximately 3/4 
of its window height. 


/LEFT:[n] 


Scrolls left over the display’s text by n columns to reveal text beyond the 
left window border. You cannot scroll past column 1. If n is omitted, the 
display is scrolled left by 8 columns. 


/RIGHTI:n] 


Scrolls right over the display’s text by n columns to reveal text beyond the 
right window border. You cannot scroll past column 255. If n is omitted, 
the display is scrolled right by 8 columns. 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name, 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


SCROLL 


Use any of the following process-identifier-type keywords: 


PROCESS _ NAME The display-name suffix is the VMS process name. 
PROCESS_NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 


/TOP 
Scrolls up to the top of the display’s text. 


/UP[:n] 

Scrolls up over the display’s text by n lines to reveal text further up in the 
display. If n is omitted, the display is scrolled by approximately 3/4 of its 
window height. 





DESCRIPTION 


The SCROLL command moves a display up, down, right, or left relative 
to its window so that various parts of the display text can be made visible 
through the window. 


Use the SELECT/SCROLL command to select the target display for the 
SCROLL command (the current scrolling display). 


See Appendix B for keypad-key definitions associated with the SCROLL 
command. 


Related commands: SELECT. 





EXAMPLES 


DBG> SCROLL/LEFT 


This command scrolls the current scrolling display to the left by 8 columns. 


DBG> SCROLL/UP:4 ALPHA 


This command scrolls display ALPHA 4 lines up. 
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SEARCH 


Searches the source code for a specified string and displays source lines that 
contain an occurrence of the string. 








FORMAT SEARCH [range] [string] 

PARAMETERS /ange 
Specifies a program region to be searched. Use any of the following 
formats: 
mod-name Searches the specified module from line 0 to the 
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mod-name\line-num 


mod-name\line-num:line-num 


line-num 


line-num:line-num 


null (no entry) 


string 


end of the module. 


Searches the specified module from the specified 
line number to the end of the module. 


Searches the specified module from the line number 
specified on the left of the colon to the line number 
specified on the right. 


Uses the current scope to find a module and 
searches that module from the specified line number 
to the end of the module. The current scope is that 
established by a previous SET SCOPE command, 
or the PC scope if no SET SCOPE command was 
entered. If you specify a scope search list with the 
SET SCOPE command, the debugger searches only 
the module associated with the first named scope. 


Uses the current scope to find a module and 
searches that module from the line number specified 
on the left of the colon to the line number specified 
on the right. The current scope is that established 
by a previous SET SCOPE command, or the PC 
scope if no SET SCOPE command was entered. If 
you specify a scope search list with the SET SCOPE 
command, the debugger searches only the module 
associated with the first named scope. 


Searches the same module as that from which 

a source line was most recently displayed (as a 
result of a TYPE, EXAMINE/SOURCE, or SEARCH 
command, for example), beginning at the first 

line following the line most recently displayed and 
continuing to the end of the module. 


Specifies the source code characters for which to search. If you do not 
specify a string, the string specified in the last SEARCH command, if any, 


is used. 


You must enclose the string in quotation marks (") or apostrophes (’) 
under the following conditions: 


e The string has any leading or ending space or tab characters 


SEARCH 


e The string contains an embedded semicolon 


e The range parameter is null 


If the string is enclosed in quotation marks, use two consecutive quotation 
marks ("") to indicate an enclosed quotation mark. If the string is 
enclosed in apostrophes, use two consecutive apostrophes (’ ’ ) to indicate 
an enclosed apostrophe. 





QUALIFIERS 


/ALL 


Specifies that the debugger search for all occurrences of the string in the 
specified range and display every line containing an occurrence of the 
string. 


ADENTIFIER 


Specifies that the debugger search for an occurrence of the string in 
the specified range but display the string only if it is not bounded on 
either side by a character that can be part of an identifier in the current 
language. 7 


/NEXT 


Specifies that the debugger search for the next occurrence of the string in 


the specified range and display only the line containing this occurrence. 
This is the default. 


/STRING 


Specifies that the debugger search for and display the string as specified, 
and not interpret the context surrounding an occurrence of the string, as it 
does in the case of /IDENTIFIER. This is the default. 





DESCRIPTION 


The SEARCH command displays the lines of source code that contain an 
occurrence of a specified string. 


When specifying a module name with the SEARCH command, note 
that the module must be set. Use the SHOW MODULE command 
to determine whether a particular module is set. Then use the SET 
MODULE command, if necessary. 


SEARCH command qualifiers determine whether the debugger: (1) 
searches for all occurrences (/ALL) of the string or only the next occurrence 
(/NEXT); and (2) displays any occurrence of the string (/STRING) or only 
those occurrences in which the string is not bounded on either side by a 
character that can be part of an identifier in the current language 
(IDENTIFIER). 


If you plan to enter several SEARCH commands with the same qualifier, 
you can first use the SET SEARCH command to establish a new default 
qualifier (for example, SET SEARCH ALL makes the SEARCH command 
behave like SEARCH/ALL). Then you do not have to use that qualifier 
with the SEARCH command. You can override the current default 
qualifiers for the duration of a single SEARCH command by specifying 
other qualifiers. 


Related commands: (SET, SHOW) SEARCH, (SET, SHOW) LANGUAGE, 
(SET, SHOW) SCOPE, (SET, SHOW) MODULE. 
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SEARCH 





EXAMPLES 


DBG> SEARCH/STRING/ALL 40:50 D 
module COBOLTEST 


40: 02 D2N COMP-2 VALUE -234560000000. 

41: 02 D COMP-2 VALUE 222222.33. 

42: 02 DN COMP-2 VALUE -222222.333333. 

47: Q2 DRO COMP-2 VALUE 0.1. 

48: 02 DR5 COMP-2 VALUE 0.000001. 

49: 02 DR10 COMP-2 VALUE 0.00000000001. 

90: O02 DR15 COMP-2 VALUE 0.0000000000000001. 
DBG> 


This command searches for all occurrences of the letter D in lines 40 to 50 
of the module COBOLTEST, the module that is in the current scope. 


DBG> SEARCH/IDENTIFIER/ALL 40:50 D 
module COBOLTEST 

41: 02 D 
DBG> 


COMP-2 VALUE 222222.33. 


This command searches for all occurrences of the letter D in lines 40 to 50 
of the module COBOLTEST. The debugger displays the only line where the 
letter D (the search string) is not bounded on either side by a character 
that can be part of an identifier in the current language. 


DBG> SEARCH/NEXT 40:50 D 
module COBOLTEST 

40: O02 D2N 
DBG> 


COMP-2 VALUE -234560000000. 


This command searches for the next occurrence of the letter D in lines 40 
to 50 of the module COBOLTEST. 


DBG> SEARCH/NEXT 
module COBOLTEST 

41: 02 D 
DBG> 


COMP-2 VALUE 222222.33. 


This command searches for the next occurrence of the letter D. The 
debugger assumes D to be the search string because D was the last one 
entered and no other search string was specified. 


DBG> SEARCH 43 D 
module COBOLTEST 

47: 02 DRO 
DBG> 


COMP-2 VALUE 0.1. 


This command searches for the next occurrence (by default) of the letter D, 
starting with line 43. 
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SELECT 


Selects a screen display as the current error, input, instruction, output, 
program, prompt, scrolling, or source display. 





FORMAT 


SELECT (/disp-name] 





PARAMETERS 


disp-name 
Specifies the display to be selected. You can specify any one of the 
following, with the restrictions noted in the qualifier descriptions: 


e A predefined display (SRC, OUT, INST, REG, and PROMPT) 
¢ A display previously created with the DISPLAY command 


¢ A display built-in symbol: 2CURDISP, Z2CURSCROLL, %NEXTDISP, 
%NEXTINST, ZNEXTOUTPUT, SZNEXTSCROLL, ZNEXTSOURCE 


If you omit this parameter and do not specify a qualifier, you "unselect" 
the current scrolling display (no display then has the scrolling attribute). 
If you omit this parameter but specify a qualifier (INPUT, /SOURCE, 
and so on), you unselect the current display with that attribute (see the 
qualifier descriptions). 





QUALIFIERS 


/ERROR 


If you specify a display, selects it as the current error display. This 
causes all debugger diagnostic messages to go to that display. The display 
specified must be either an output display or the PROMPT display. 


If you do not specify a display, the PROMPT display is selected as the 
current error display. 


By default, the PROMPT display has the error attribute. 
ANPUT 


If you specify a display, selects it as the current input display. This 
causes that display to echo debugger input (which always appears in 
the PROMPT display). The display specified must be an output display. 


If you do not specify a display, the current input display is unselected and 
debugger input is not echoed to any display (debugger input appears only 
in the PROMPT display). 


By default, no display has the input attribute. 


/AINSTRUCTION 


If you specify a display, selects it as the current instruction display. This 
causes the output of all EXAMINE/INSTRUCTION commands to go to 
that display. The display specified must be an instruction display. 


If you do not specify a display, the current instruction display is unselected 
and no display has the instruction attribute. 
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By default, for all languages except MACRO, no display has the instruction 
attribute. If the language is set to MACRO, the INST display has the 
instruction attribute by default. 


/OUTPUT 

If you specify a display, selects it as the current output display. This 
causes debugger output that is not already directed to another display to 
go to that display. The display specified must be either an output display 
or the PROMPT display. 


If you do not specify a display, the PROMPT display is selected as the 
current output display. 


By default, the OUT display has the output attribute. 
/PROGRAM 


If you specify a display, selects it as the current program display. This 
causes the debugger to try to force program input and output to that 
display. Currently, only the PROMPT display can be specified. 


If you do not specify a display, the current program display is unselected 
and program input and output are no longer forced to the specified display. 


By default, the PROMPT display has the program attribute, except on 
workstations, where the program attribute is unselected. 


/PROMPT 


Selects the specified display as the current prompt display. This is where 
the debugger prompts for input. Currently, only the PROMPT display 
can be specified. Moreover, you cannot unselect the PROMPT display (the 
PROMPT display always has the prompt attribute). 


/SCROLL 

If you specify a display, selects it as the current scrolling display. This 
is the default display for the SCROLL, MOVE, and EXPAND commands. 
Although any display can have the scroll attribute, note that you can use 
only the MOVE and EXPAND commands (not the SCROLL command) 
with the PROMPT display. 


If you do not specify a display, the current scrolling display is unselected 
and no display has the scroll attribute. 


By default, for all languages except MACRO, the SRC display has the 
scroll attribute. If the language is set to MACRO, the INST display has 
the scroll attribute by default. 


Note: If no qualifier is specified, /SCROLL is assumed by default. 
/SOURCE 


If you specify a display, selects it as the current source display. This causes 
the output of all TYPE and EXAMINE/SOURCE commands to go to that 
display. The display specified must be a source display. 


If you do not specify a display, the current source display is unselected and 
no display has the source attribute. 


By default, for all languages except MACRO, the SRC display has the 
source attribute. If the language is set to MACRO, no display has the 
source attribute by default. 


SELECT 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 
PROCESS_NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFTX). 





DESCRIPTION Attributes are used to select the current scrolling display and to direct 
various types of debugger output to particular displays. This gives you 
the option of mixing or isolating different types of information, such 
as debugger input, output, diagnostic messages, and so on in scrollable 
displays. 


You use the SELECT command with one or more qualifiers (/ERROR, 
/SOURCE, and so on) to assign one or more corresponding attributes to a 
display. If you do not specify a qualifier, the /SCROLL qualifier is assumed 
by default. 


If you use the SELECT command without specifying a display name, in 
general the attribute assignment indicated by the command qualifier is 
canceled (unselected). To reassign display attributes you must use another 
SELECT command. See the individual qualifier descriptions for details. 


See Appendix B for keypad-key definitions associated with the SELECT 
command. . 


Related commands: SHOW SELECT, SCROLL, MOVE, EXPAND, 
DISPLAY. 





EXAMPLES 


DBG> SELECT/SOURCE/SCROLL SRC2 


This command selects display SRC2 as the current source and scrolling 
display. 
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SELECT 


DBG> SELECT/INPUT/ERROR OUT 


This command selects display OUT as the current input and error display. 
This causes debugger input, debugger output (assuming OUT is the 
current output display), and debugger diagnostic messages to be logged 
in the OUT display in the correct sequence. 


DBG> SELECT/SOURCE 


This command unselects (deletes the source attribute from) the currently 
selected source display. The output of a TYPE or EXAMINE/SOURCE 
command then goes to the currently selected output display. 
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SET ABORT KEY 


SET ABORT KEY 


Assigns the debugger’s abort function to another CTRL—key sequence. By 
default, the CTRL/C sequence performs the abort function. 





FORMAT SET ABORT_KEY =C7/AL_character 





PARAMETERS -_ character 
Specifies the key you press while holding down the CTRL key. You can 


specify any alphabetic character. 





DESCRIPTION _ By default, the CTRL/C sequence, when entered within a debugging 
session, aborts the execution of a debugger command and interrupts 
program execution. The SET ABORT_KEY command enables you to 
assign the abort function to another CTRL—key sequence. This might be 
necessary if your program has a CTRL/C AST service routine enabled. 


Note that many CTRL—key sequences have VMS predefined functions, 
and the SET ABORT_KEY command enables you to override such 
definitions (see the VMS DCL Concepts Manual). Some of the CTRL— 
key characters not used by the VMS operating system are G, K, N, and 
P. 


The SHOW ABORT_KEY command identifies the CTRL—key sequence 
currently in effect for the abort function. 


Do not use CTRL/Y from within a debugging session. Always use either 
CTRL/C or an equivalent CTRL—key sequence established with the SET 
ABORT_KEY command. 


Related commands: CTRL/C, SHOW | ABORT KEY. CTRL/Y. 





EXAMPLE 


DBG> SHOW ABORT KEY 
Abort Command Key is CTRL C 
DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 


| ee 

© 

© 

co 
Ooo 0 Oo 
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SET ABORT KEY 


SDEBUG~W-ABORTED, command aborted by user request 


DEG? -SOET: ABORT KEY -=-CTRL-. 2 
DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 
1000: 
1004: 
1008: 
LOLZ: 
1016: 
SDEBUG-W~-ABORTED, command aborted by user request 
DBG> 


oOO00 0 


This sequence of commands shows the following entities: 
e Use of the (default) CTRL/C sequence to perform the abort function. 


e Use of the SET ABORT_KEY command to reassign the abort function 
to the CTRL/P sequence. 
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SET ATSIGN 


SET ATSIGN 


Establishes the default file specification that the debugger uses when 
searching for command procedures. 





FORMAT SET ATSIGN _file-spec 





PARAMETERS _file-spec 
Specifies any part of a VMS file specification (for example, a directory 


name or a file type) that the debugger is to use by default when searching 
for a command procedure. If you do not supply a full file specification, 
the debugger assumes SYS$DISK:[ JDEBUG.COM as the default file 


specification for any missing field. 


You can specify a logical name that translates to a search list. In this case, 
the debugger processes the file specifications in the order they appear in 
the search list until the command procedure is found. 





DESCRIPTION When you invoke a command procedure during a debugging session, 
the debugger, by default, assumes that its file specification is 
SYS$DISK:[ JDEBUG.COM. The SET ATSIGN command enables you 
to override this default. 


Related commands: @file-spec, SHOW ATSIGN. 





EXAMPLE 


DBG> SET ATSIGN USER: [JONES.DEBUG] .DBG 
DBG> @TEST 


In this example, when the user invokes @TEST, the debugger looks for the 
file TEST.DBG in USER:[JONES.DEBUG]. 
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SET BREAK 


SET BREAK 


Establishes a breakpoint at the location denoted by an address expression, at 
instructions of a particular class, or at the occurrence of specified events. 





FORMAT SET BREAK /address-expression/, ... ]] 
[WHEN (conditional-expression)] 
[DO(command; ... ])] 





PARAMETERS address-expression 


Specifies an address expression (a program location) at which a breakpoint 
is to be set. With high-level languages, this is typically a line number, 

a routine name, or a label, and can include a path name to specify 

the entity uniquely. More generally, an address expression can also 

be a memory address or a register and can be composed of numbers 
(offsets) and symbols, as well as one or more operators, operands, or 
delimiters. Appendix D identifies the operators that can be used in 
address expressions. 


Do not specify the asterisk wildcard character (*). Do not specify 

an address expression with /ACTIVATING, /BRANCH, /CALL, 
/EXCEPTION, ANSTRUCTION[=(opcode-list)], INTO, /[NOJJSB, /LINE, 
/OVER, /[NOJSHARE, /[NO]SYSTEM, /TERMINATING, or /VECTOR_ 
INSTRUCTION. The /MODIFY and /RETURN qualifiers are used with 
specific kinds of address expressions. 


If you specify a memory address or an address expression whose value 

is not a symbolic location, check (with the EXAMINE command) that 

an instruction actually begins at the byte of memory so indicated. If 

an instruction does not begin at this byte, a run-time error can occur 
when an instruction including that byte is executed. When you set a 
breakpoint by specifying an address expression whose value is not a 
symbolic location, the debugger does not verify that the location specified 
marks the beginning of an instruction. CALLS and CALLG routines start 
with an entry mask. 


command 


Specifies a debugger command to be executed as part of the DO clause 
when break action is taken. 


conditional-expression 

Specifies a conditional expression in the currently set language that is to 
be evaluated when execution reaches the breakpoint. If the expression 
is true, break action occurs, and the debugger reports that a break has 
occurred. If the expression is false, break action does not occur. In this 
case, a report is not issued, the commands specified by the DO clause are 
not executed, and program execution is continued. 


CD-130 


SET BREAK 





QUALIFIERS 


/ACTIVATING 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


Causes the debugger to break when a new process comes under debugger 
control. The debugger prompt is displayed when the first process comes 
under debugger control. This enables you to enter debugger commands 
before the program has started execution. Do not specify an address 
expression with /ACTIVATING. See also /TERMINATING. 


/AFTER:n 


Specifies that break action not be taken until the nth time the designated 
breakpoint is encountered (n is a decimal integer). Thereafter, the 
breakpoint occurs every time it is encountered provided that conditions 
in the WHEN clause (if specified) are true. The command SET BREAK 
/AFTER:1 has the same effect as the SET BREAK command. 


/BRANCH 


Causes the debugger to break on every branch instruction encountered 
during program execution. Do not specify an address expression with 
/BRANCH. See also ANTO and /OVER. 


/CALL 


Causes the debugger to break on every call instruction encountered during 
program execution, including the RET instruction. Do not specify an 
address expression with /CALL. See also INTO and /OVER. 


/EVENT=event-name 
Note: This qualifier applies to Ada and SCAN programs. See the 
VAX Ada and VAX SCAN documentation for complete information. 


Causes the debugger to break on the specified event (if that event is 
defined and detected by the run-time system). If you specify an address 
expression with /EVENT, causes the debugger to break whenever the 
specified event occurs for that address expression. Event names depend on 
the run-time facility and are identified in Appendix E for Ada and SCAN. 
You can display the event names associated with the current run-time 
facility by entering the SHOW EVENT_FACILITY command. Note that 
you cannot specify an address expression with certain event names. 


/EXCEPTION 


Causes the debugger to break whenever an exception is signaled. The 
break action occurs before any application-declared exception handlers are 
invoked. Do not specify an address expression with /EXCEPTION. 


As a result of a SET BREAK/EXCEPTION command, whenever your 
program generates an exception, the debugger suspends program 
execution, reports the exception, and displays its prompt. When you 
resume execution from an exception breakpoint, the behavior is as follows: 


e Ifyou enter a GO command without an address-expression parameter, 
the exception is resignaled, thus allowing any application-declared 
exception handler to execute. 


e If you enter a GO command with an address-expression parameter, 
program execution continues at the specified location, thus inhibiting 
the execution of any application-declared exception handler. 
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e If you enter a STEP command, the debugger steps into any 
application-declared exception handler. If there is no application- 
declared handler for that exception, the debugger resignals the 
exception. 


e If you enter a CALL command, the routine specified is executed. 
If a routine is called with the CALL command directly after an 
exception breakpoint has been triggered, no breakpoints, tracepoints, 
or watchpoints set within that routine are triggered. However, they 
are triggered if the CALL command is given at another time. 


/AINSTRUCTION[=(opcodef, .. . ])] 


If you do not specify an opcode, causes the debugger to break on every 
instruction encountered during program execution. If you specify one or 
more opcodes, causes the debugger to break on every instruction whose 
opcode is in the list. 


Do not specify an address expression with this qualifier. If you specify a 
vector instruction, do not include an instruction qualifier (/U, /V, /M, /0, or 
/1) with the instruction mnemonic. See also /INTO and /OVER. 


ANTO 

Applies only to breakpoints set with /BRANCH, /CALL, 
IINSTRUCTION[=(opcode-list)], /LINE, or /VECTOR_INSTRUCTION; 
that is, when an address expression is not explicitly specified. When used 
with those qualifiers, causes the debugger to break at the specified points 
within called routines (as well as within the routine in which execution is 
currently suspended). The /INTO qualifier is the default behavior and is 
the opposite of /OVER. 


When using /INTO, you can further qualify the break action with the 
/[NO]JSB, /INOJSHARE, and /[NOJSYSTEM qualifiers. 


/JSB 


/NOJSB 

Qualifies /INTO. Use /[LNO]JJSB only with /INTO and one of the following 
qualifiers: /BRANCH, /CALL, ANSTRUCTION[=(opcode-list)], /LINE, 

or /VECTOR_INSTRUCTION. The /JSB qualifier is the default for all 
languages except DIBOL. The /JSB qualifier permits the debugger to 
break within routines that are called by the JSB or CALL instruction. The 
/NOJSB qualifier (the DIBOL default) specifies that breakpoints not be set 
within routines called by JSB instructions. In DIBOL, application-declared 
routines are called by the CALL instruction and DIBOL run-time library 
routines are called by the JSB instruction. Do not specify an address 
expression with /[NO]JSB. 


/LINE 


Causes the debugger to break on the beginning of each source line 
encountered during program execution. Do not specify an address 
expression with /LINE. See also /INTO and /OVER. 


/MODIFY 


Causes the debugger to break on every instruction that writes to and 
modifies the value of the location indicated by the address expression. The 
address expression is typically a variable name. 


SET BREAK 


The SET BREAK/MODIFY command acts exactly like a SET WATCH 
command and operates under the same restrictions. 


If you specify an absolute address for the address expression, the debugger 
might not be able to associate the address with a particular data object. 
In this case, the debugger uses a default length of 4 bytes. You can change 
this length, however, by setting the type to either WORD (SET TYPE 
WORD, which changes the default length to 2 bytes) or BYTE (SET 
TYPE BYTE, which changes the default length to 1 byte). SET TYPE 
LONGWORD restores the default length of 4 bytes. 


/OVER 

Applies only to breakpoints set with /BRANCH, /CALL, 
ANSTRUCTION[=(opcode-list)], /LINE, or /VECTOR_INSTRUCTION; 
that is, when an address expression is not explicitly specified. When used 
with those qualifiers, causes the debugger to break at the specified points 
only within the routine in which execution is currently suspended (not 
within called routines). The /OVER qualifier is the opposite of /INTO (the 
default behavior). 


/RETURN 


Causes the debugger to break on the RET (return) instruction of the 
routine associated with the specified address expression (which can be a 
routine name, line number, and so on). This qualifier can only be applied 
to routines called with a CALLS or CALLG instruction; it cannot be used 
with JSB routines. Breaking on the RET instruction enables you to inspect 
the local environment (for example, obtain the values of local variables) 
before the RET instruction deletes the routine’s call frame from the call 
stack. 


For this qualifier, the address-expression parameter is an instruction 
address within a CALLS or CALLG routine. It can simply be a routine 
name, in which case it specifies the routine start address. However, you 
can also specify another location in a routine, so you can see only those 
returns that are taken after a certain code path is followed. 


A SET BREAK/RETURN command cancels a previous SET BREAK 
command if the same address expression is specified. 


/SHARE (default) 


/NOSHARE 

Qualifies /INTO. Use /[LNOJSHARE only with /INTO and one of the 
following qualifiers: /BRANCH, /CALL, INSTRUCTION|[=(opcode-list)], 
/LINE, or /VECTOR_INSTRUCTION. The /SHARE qualifier permits 
the debugger to break within shareable image routines as well as other 
routines. The /NOSHARE qualifier specifies that breakpoints not be set 


within shareable images. Do not specify an address expression with 
/[NOJSHARE. 


/SILENT 
/NOSILENT (default) 


Controls whether the "break ... " message and the source line for 

the current location are displayed at the breakpoint. The /NOSILENT 
qualifier specifies that the message is displayed. The /SILENT qualifier 
specifies that the message and the source line are not displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NOJSOURCE. 
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/SOURCE (default) 
/NOSOURCE 


Controls whether the source line for the current location is displayed 

at the breakpoint. The /SOURCE qualifier specifies that the source line 

is displayed. The /NOSOURCE qualifier specifies that no source line is 
displayed. The /SILENT qualifier overrides /SOURCE. See also SET STEP 
[NOJSOURCE. 


/SYSTEM (default) 


/NOSYSTEM 

Qualifies INTO. Use /[NOJSYSTEM only with /INTO and one of the 
following qualifiers: /BRANCH, /CALL, /INSTRUCTION[=(opcode-list)], 
/LINE, or /VECTOR_INSTRUCTION. The /SYSTEM qualifier permits 
the debugger to break within system routines (P1 space) as well as other 
routines. The /NOSYSTEM qualifier specifies that breakpoints not be 


set within system routines. Do not specify an address expression with 
/[NOJSYSTEM. 


/TEMPORARY 


Causes the breakpoint to disappear after it is triggered (the breakpoint 
does not remain permanently set). 


/TERMINATING 


Causes the debugger to break when a process performs an image exit. 
Note that the debugger always gains control and displays its prompt when 
the last image of a one-process or multiprocess program exits. A process is 
terminated when the image has executed the $EXIT system service and all 
of its exit handlers have executed. Do not specify an address expression 
with /TERMINATING. See also /ACTIVATING. 


/VECTOR_INSTRUCTION 
Note: This qualifier applies to vectorized programs. 


Causes the debugger to break on every vector instruction encountered 
during program execution. Do not specify an address expression with 
/VECTOR_INSTRUCTION. See also /INTO and /OVER. 





DESCRIPTION When a breakpoint is triggered, the debugger takes the following action: 
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1 Suspends program execution at the breakpoint location. 


2 If/AFTER was specified when the breakpoint was set, checks the 
AFTER count. If the specified number of counts has not been reached, 
execution is resumed and the debugger does not perform the remaining 
steps. 


3 Evaluates the expression in a WHEN clause, if one was specified 
when the breakpoint was set. If the value of the expression is false, 
execution is resumed and the debugger does not perform the remaining 
steps. 


4 Reports that execution has reached the breakpoint location by issuing 
a "break ... " message, unless /SILENT was specified. 


SET BREAK 


5 Displays the line of source code at which execution is suspended, 
unless /NOSOURCE or /SILENT was specified when the breakpoint 
was set, or SET STEP NOSOURCE was entered previously. 


6 Executes the commands in a DO clause, if one was specified when 
the breakpoint was set. If the DO clause contains a GO command, 
execution continues and the debugger does not perform the next step. 


7 Issues the prompt. 


You set a breakpoint at a particular location in your program by specifying 
an address expression with the SET BREAK command. You set a 
breakpoint on consecutive source lines, classes of instructions, or events 
by specifying a qualifier with the SET BREAK command. Generally, you 
must specify either an address expression or a qualifier, but not both. 
The only exception is with the /EVENT qualifier, which requires that you 
specify an event name keyword and permits you also to specify an address 
expression for certain event names. 


The /LINE qualifier sets a breakpoint on each line of source code. 


The following qualifiers set breakpoints on classes of instructions. Note 
that use of these qualifiers and of the /LINE qualifier causes the debugger 
to trace every instruction of your program as it executes and thus 
significantly slows down execution: 


/BRANCH 

/CALL 
AINNSTRUCTION[=(opcodel, ... ])] 
/RETURN 
/VECTOR_INSTRUCTION 


The following qualifiers set breakpoints on classes of events: 


/ACTIVATING 
/EVENT=event-name 
/EXCEPTION 
/TERMINATING 


The following qualifiers affect what happens at a routine call: 


INTO 
[NOJJSB 
/OVER 
/[NOJSHARE 
/NO|SYSTEM 


The following qualifiers affect what output is displayed when a breakpoint 
is reached: 

ANOJSILENT 

/[[INOJSOURCE 
The following qualifiers affect the timing and duration of breakpoints: 


/AFTER:n 
/TEMPORARY 
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SET BREAK 


The /MODIFY qualifier is used to monitor changes at program locations 
(typically changes in the values of variables). 


If you set a breakpoint at a location currently used as a tracepoint, the 
tracepoint is canceled in favor of the breakpoint, and vice versa. 


Breakpoints can be user defined or predefined. User defined breakpoints 

are those that you set explicitly with the SET BREAK command. 

Predefined breakpoints, which depend on the type of program you 

are debugging (for example, Ada or multiprocess), are established 

automatically when you invoke the debugger. Use the SHOW BREAK 
command to identify all breakpoints that are currently set. Any predefined 

breakpoints are identified as such. 


User defined and predefined breakpoints are set and canceled 
independently. For example, a location or event can have both a 
user defined and a predefined breakpoint. Canceling the user defined 
breakpoint does not affect the predefined breakpoint, and conversely. 


Related commands: (SHOW, CANCEL) BREAK, CANCEL ALL, SET 
TRACE, SET WATCH, GO, STEP, (SET, SHOW) EVENT_FACILITY, SET 





STEP [NOJSOURCE. 
EXAMPLES 
DBG> SET BREAK SWAP\%LINE 12 
This command causes the debugger to break on line 12 of module SWAP. 
DBG> SET BREAK/AFTER:3 SUB2 
This command causes the debugger to break on the third and subsequent 
times that SUB2 (a routine) is executed. 
DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAMINE D; STEP; EXAMINE Y; GO) 
This command causes the debugger to break at location LOOP1. At 
the breakpoint, the following commands are issued, in the order given: 
EXAMINE D, STEP, EXAMINE Y, and GO. The /NOSOURCE qualifier 
suppresses the display of source code at the breakpoint. 
DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y) 
This command causes the debugger to break on routine ROUTS3 when X is 
greater than 4. At the breakpoint, the command EXAMINE Y is issued. 
DBG> SET BREAK/TEMPORARY 1440 
DBG> SHOW BREAK 
breakpoint at 1440 [temporary] 
DBG> 
This command sets a temporary breakpoint at memory address 1440. 
After that breakpoint is triggered, it disappears. 
§ DBG> SET BREAK/LINE 


This command causes the debugger to break on the beginning of every 
source line encountered during program execution. 


CD-—136 


DBG> 
DBG> 


DBG> 


DBG> 


DBG> 


DBG> 


DBG> 


DBG> 


SET 
SET 


SET 


SEL 


SET 


SET 


SET 


SET 


SET BREAK 


BREAK/LINE WHEN (X .NE. 0) 
BREAK/INSTRUCTION WHEN (X .NE. 0) 


These two commands cause the debugger to break when X is not equal 
to 0. The first command tests for the condition at the beginning of every 
source line encountered during execution. The second command tests for 
the condition at each instruction. 


BREAK/ INSTRUCTION=ADDL3 


This command causes the debugger to break whenever the instruction 
ADDL3 is about to be executed. 


BREAK/LINE/ INTO/NOSHARE/NOSYSTEM 


This command causes the debugger to break on the beginning of every 
source line, including lines in called routines (INTO) but not in shareable 
image routines ((NOSHARE) or system routines (/(NOSYSTEM). 


BREAK/RETURN ROUT4 


This command causes the debugger to break whenever the RET instruction 
of routine ROUT4 is about to be executed. 


BREAK/RETURN %SLINE 14 


This command causes the debugger to break whenever the RET instruction 
of the routine that includes line 14 is about to be executed. This form of 
the command is useful if execution is currently suspended within a routine 
and you want to set a breakpoint on that routine’s RET instruction. 


BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 


This command causes the debugger to break whenever an exception is 
signaled. At the breakpoint, the commands SET MODULE/CALLS and 
SHOW CALLS are issued. 


BREAK/EVENT=RUN RESERVE, %TASK 3 


This command sets two breakpoints, which are associated with the Ada 
tasks RESERVE and task 3, respectively. Each breakpoint is triggered 
whenever its associated task makes a transition to the RUN state. 


DBG 1> SET BREAK/ACTIVATING 


This command causes the debugger to break whenever a process of a 
multiprocess program is brought under debugger control. 
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SET DEFINE 


Establishes a default qualifier (ADDRESS, /COMMAND, /PROCESS_ GROUP, 
or /VALUE) for the DEFINE command. 





FORMAT SET DEFINE define-default 





PARAMETERS  define-default 
Specifies the default to be established for the DEFINE command. Valid 
keywords (which correspond to DEFINE command qualifiers) are as 


follows: 

ADDRESS Subsequent DEFINE commands are treated as DEFINE 
/ADDRESS. This is the default. 

COMMAND Subsequent DEFINE commands are treated as DEFINE 
/COMMAND. 

PROCESS_GROUP Subsequent DEFINE commands are treated as DEFINE 
/PROCESS_GROUP. 

VALUE Subsequent DEFINE commands are treated as DEFINE 
NVALUE. 





DESCRIPTION = The SET DEFINE command establishes a default qualifier for subsequent 
DEFINE commands. The parameters that you specify in the SET DEFINE 
command have the same names as the DEFINE command qualifiers. 
DEFINE command qualifiers determine whether the DEFINE command 
binds a symbol to an address, a command string, a list of processes, or a 
value. 


You can override the current DEFINE default for the duration of a 
single DEFINE command by specifying another qualifier. Use the SHOW 
DEFINE command to identify the current DEFINE defaults. 


Related commands: SHOW DEFINE, DEFINE, DEFINE/PROCESS_ 
GROUP, DELETE, SHOW SYMBOL/DEFINED. 





EXAMPLE 


DBG> SET DEFINE VALUE 


The SET DEFINE VALUE command specifies that subsequent DEFINE 
commands are treated as DEFINE/VALUE. 
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SET EDITOR 


Establishes the editor that is invoked by the EDIT command. 





FORMAT 


SET EDITOR [command-line] 





PARAMETERS 


command-line 
Specifies a command line to invoke a particular editor on your system 
when you use the EDIT command. 


You must specify a command line unless you use the /CALLABLE_EDT, 
/CALLABLE_LSEDIT, or /CALLABLE_TPU qualifiers. If you do not use 
one of these qualifiers, the editor specified in the SET EDITOR command 
line is spawned to a subprocess when you enter the EDIT command. 


You can specify a command line with the /CALLABLE _LSEDIT and 
/CALLABLE_TPU qualifiers, but not with the /CALLABLE_EDT qualifier. 





QUALIFIERS 


/CALLABLE EDT 

Specifies that the callable version of the EDT editor is invoked when 
you use the EDIT command. Do not specify a command line with 
/CALLABLE_EDT (a command line of "EDT" is used). 


/CALLABLE_LSEDIT 

Specifies that the callable version of the VAX Language-Sensitive Editor 
(LSEDIT) is invoked when you use the EDIT command. If you also specify 
a command line, it is passed to callable LSEDIT. If you do not specify a 
command line, the default command line is "LSEDIT". 


/CALLABLE_TPU 

Specifies that the callable version of the VAX Text Processing Utility 
(VAXTPU) is invoked when you use the EDIT command. If you also 
specify a command line, it is passed to callable VAXTPU. If you do not 
specify a command line, the default command line is "TPU". 


/START_POSITION 
/NOSTART_POSITION (default) 
Note: Currently, only VAXTPU and the VAX Language-Sensitive 


Editor (specified either as TPU or /CALLABLE_TPU, and LSEDIT 
or /CALLABLE_LSEDIT, respectively) supports /START POSITION. 


Controls whether the /START_POSITION qualifier is appended to the 
specified or default command line when the EDIT command is used. This 
qualifier affects the initial position of the editor’s cursor. By default, 
(/NOSTART_POSITION), the editor’s cursor is placed at the beginning of 
source line 1, regardless of which line is centered in the debugger’s source 
display or whether a line number is specified in the EDIT command. If 
/START_POSITION is specified, the cursor is placed either on the line 
whose number is specified in the EDIT command, or (if no line number is 
specified) on the line that is centered in the current source display. 
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SET EDITOR 





DESCRIPTION 


The SET EDITOR command can be used to specify any editor that is 
installed on your system. In general, the command line specified as 
parameter to the SET EDITOR command is spawned and executed in 

a subprocess. However, if you use EDT, LSEDIT, or VAXTPU, you have 
the option of invoking these editors in a more efficient way. You can 
specify the /CALLABLE_EDT, /CALLABLE_LSEDIT, or /CALLABLE_ 
TPU qualifiers, which cause the callable versions of EDT, LSEDIT, and 
VAXTPU, respectively, to be invoked by the EDIT command. In the case 
of LSEDIT and VAXTPU, you can also specify a command line that is 
executed by the callable editor. 


Related commands: SHOW EDITOR, EDIT, (SET, SHOW, CANCEL) 
SOURCE. 





EXAMPLES 


DBG> SET EDITOR ’@MAILSEDIT ""/ 


This command causes the EDIT command to spawn the command line 
"@MAIL$EDIT "”, which invokes the same editor as you use in MAIL. 


DBG> SET EDITOR/CALLABLE TPU 


This command causes the EDIT command to invoke callable VAXTPU with 
the default command line of TPU. 


DBG> SET EDITOR/CALLABLE TPU TPU/SECTION=MYSECINI.TPUSSECTION 


This command causes the EDIT command to invoke callable VAXTPU with 
the command line TPU/SECTION=MYSECINI.TPU$SECTION. 


DBG> SET EDITOR/CALLABLE LSEDIT/START_ POSITION 
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This command causes the EDIT command to invoke callable LSEDIT 
with the default command line of LSEDIT. Also the /START_POSITION 
qualifier is appended to the command line, so that the editing session 
starts on the source line that is centered in the debugger’s current source 
display. 


SET EVENT FACILITY 


SET EVENT FACILITY 


Establishes the run-time library facility for eventpoints that are set with the 
SET BREAK/EVENT and SET TRACE/EVENT commands. 


Note: This command applies to Ada and SCAN programs. See the VAX 
Ada and VAX SCAN documentation for complete information. 





FORMAT 


SET EVENT FACILITY  facility-name 





PARAMETERS 


facility-name 
Specifies a run-time library facility for eventpoints. Valid keywords are as 
follows: 


ADA Enables recognition of Ada-specific events when you use the (SET, 
CANCEL) BREAK/EVENT and (SET, CANCEL) TRACE/EVENT commands. 
Valid Ada event names are identified in Appendix E. 


SCAN _ Enables recognition of SCAN-specific events when you use the (SET, 
CANCEL) BREAK/EVENT and (SET, CANCEL) TRACE/EVENT commands. 
Valid SCAN event names are identified in Appendix E. 





DESCRIPTION 


The Ada event facility enables you to set breakpoints and tracepoints on 
tasking events and exception events. The SCAN event facility enables you 
to set breakpoints and tracepoints on pattern-matching events. 


Use the SHOW EVENT_FACILITY command to identify the events 
applicable to the currently set language. 


Related commands: SHOW EVENT_FACILITY, (SET, CANCEL) BREAK 
/EVENT, SHOW BREAK, (SET, CANCEL) TRACE/EVENT, SHOW 
TRACE. _ 





EXAMPLE 


DBG> SET EVENT FACILITY ADA 


This command establishes Ada as the current run-time library facility. 
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SET IMAGE 


SET IMAGE 


Loads symbol information for one or more shareable images and establishes 
the current image. 





FORMAT SETIMAGE [image-name|, ... J] 





PARAMETERS image-name 
Specifies a shareable image to be "set". Do not use the asterisk wildcard 
character (*). Do not specify an image name with /ALL. 





QUALIFIERS /ALL 
Specifies that all shareable images are set. Do not specify an image with 
/ALL. | 





DESCRIPTION The SET IMAGE command builds data structures for one or more specified 
images but does not set any modules within the images specified. 


The "current" image is the current debugging context: you have access 
to symbols in the current image. If only one image is specified with the 
SET IMAGE command, that image becomes the current image. If a list of 
images is specified, the last one in the list becomes the current image. If 
/ALL is specified, the current image is unchanged. 


Before an image can be set with the SET IMAGE command, it must 
have been linked with the (DEBUG or /TRACEBACK qualifier on the 
LINK command. If an image was linked /NOTRACEBACK, no symbol 
information is available for that image and you cannot specify it with the 
SET IMAGE command. 


Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE 
commands are available only when the image in whose context they were 
created is the current image. When you use the SET IMAGE command 
to establish a new current image, these definitions are temporarily 
unavailable. Definitions created with the DEFINE/COMMAND and 
DEFINE/KEY commands are always available for all images, however. 


Related commands: (SHOW, CANCEL) IMAGE, (SET, SHOW, CANCEL) 
MODULE, SET MODE [NOJDYNAMIC. 
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SET IMAGE 





EXAMPLE 


DBG> SET IMAGE SHARE1 
DBG> SET MODULE SUBR 
DBG> SET BREAK SUBR 


This sequence of commands shows how to set a breakpoint on routine 
SUBR in module SUBR of shareable image SHARE1. The SET IMAGE 
command sets the debugging context to SHARE1. The SET MODULE 
command loads the symbol records of module SUBR into the RST. The 
SET BREAK command sets a breakpoint on routine SUBR. 
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SET KEY 


SET KEY 


Establishes the current key state. 





FORMAT 


SET KEY 





QUALIFIERS 


/LOG (default) 
/NOLOG 


Controls whether a message is displayed indicating that the key state has 
been set. The /LOG qualifier displays the message. 


/STATE[=state-name] 
/NOSTATE (default) 


Specifies a key state to be established as the current state. You can 
specify a predefined key state, such as GOLD, or a user-defined state. A 
state name can be any appropriate alphanumeric string. The /NOSTATE 
qualifier leaves the current state unchanged. 





DESCRIPTION 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use 
this command. Keypad mode is enabled by default. 


By default, the current key state is the "DEFAULT" state. When you 
define function keys using the DEFINE/KEY command, you can use the 
/IF_STATE qualifier of that command to assign a specific state name to 
the key definition. If that state is not set when you press the key, the 
definition is not processed. The SET KEY/STATE command enables you to 
change the current state to the appropriate state. 


You can also change the current state by pressing a key that causes a 
state change (a key that was defined with the DEFINE/KEY/LOCK_ 
STATE/SET_STATE qualifier combination). 


Related commands: DEFINE/KEY, DELETE/KEY, SHOW KEY. 





EXAMPLE 


DBG> SET KEY/STATE=PROG3 
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This command changes the key state to the PROG3 state. The user can 
now use the key definitions that are associated with this state. 


SET LANGUAGE 


SET LANGUAGE 


Establishes the current language. 











FORMAT SET LANGUAGE /anguage-name 

PARAMETERS /anguage-name 
Specifies a language. Valid keywords are ADA, BASIC, BLISS, C, 
COBOL, DIBOL, FORTRAN, MACRO, PASCAL, PLI, RPG, SCAN, and 
UNKNOWN. 

DESCRIPTION — When you invoke the debugger, the debugger sets the current language 


to that in which the module containing the main program is written. 
This is usually the module containing the image transfer address. To 
debug a module written in a different source language from that of the 
main program, you can change the language with the SET LANGUAGE 
command. 


The current language setting determines how the debugger parses and 
interprets the names, operators, and expressions you specify in debugger 
commands, including things like the typing of variables, array and record 
syntax, the default radix for the entry and display of integer data, case 
sensitivity, and so on. The language setting also determines how the 
debugger formats and displays data associated with your program. 


The default radix for both data entry and display is decimal for all 
languages except BLISS and MACRO. It is hexadecimal for BLISS and 
MACRO. The default type for program locations that do not have a 
compiler generated type is longword integer. 


The SET LANGUAGE UNKNOWN command is used when debugging 

a program that is written in an unsupported language. To maximize 

the usability of the debugger with unsupported languages, the SET 
LANGUAGE UNKNOWN command causes the debugger to accept a large 
set of data formats and operators, including some that might be specific to 
only a few supported languages. 


The operators and constructs that are recognized for each SET 
LANGUAGE command parameter are identified in Appendix E. 


Related commands: SHOW LANGUAGE, SET TYPE, SET RADIX, SET 
MODE, DEPOSIT, EXAMINE, EVALUATE. 
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SET LANGUAGE 





EXAMPLES 
DBG> SET LANG COBOL 


This command establishes COBOL as the current language. 


DBG> SET LANG PASCAL 


This command establishes Pascal as the current language. 
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SET LOG 





Specifies a log file to which the debugger writes after a SET OUTPUT LOG 
command has been entered. 
FORMAT SETLOG file-spec 





PARAMETERS _file-spec 
_— Denotes the file specification of the log file. If you do not supply a full 
file specification, the debugger assumes SYS$DISK:[ JDEBUG.LOG as the 
default file specification for any missing field. 


If you specify a version number and that version of the file already 
exists, the debugger writes to the file specified, appending the log of the 
debugging session onto the end of that file. 





DESCRIPTION Note that the SET LOG command only determines the name of a log file; 
| | it does not cause the debugger to create or write to the specified file. The 
SET OUTPUT LOG command accomplishes that. 


If you have entered a SET OUTPUT LOG command but no SET LOG 
command, the debugger writes to the file SYS$DISK:[ ]DEBUG.LOG by 
default. 


If the debugger is writing to a log file and you specify another log file with 
the SET LOG command, the debugger closes the former file and begins 
writing to the file specified in the SET LOG command. 


Related commands: SHOW LOG, SET OUTPUT LOG, SET OUTPUT 
SCREEN_LOG. 





EXAMPLES 


DBG> SET LOG CALC 
| DBG> SET OUTPUT LOG 


In this example, the SET LOG command specifies the debugger log file 
to be SYS$DISK:[JCALC.LOG. The SET OUTPUT LOG command causes 
user input and debugger output to be logged to that file. 


LN | 


DBG> SET LOG "[CODEPROJ]FEB29.TMP" 
DBG> SET OUTPUT LOG 


In this example, the SET LOG command specifies the debugger log file to 
be [CODEPROJ]FEB29.TMP. The SET OUTPUT LOG command causes 
user input and debugger output to be logged to that file. 
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SET MARGINS 


SET MARGINS 


Specifies the leftmost and rightmost source-line character position at which to 
begin and end display of a source line. 





FORMAT SET MARGINS rm 
Im:irm 
Im: 
rm 





PARAMETERS /m 


The source-line character position at which to begin display of the line of 
source code (the left margin). 


rim 


The source-line character position at which to end display of the line of 
source code (the right margin). 





DESCRIPTION = The SET MARGINS command affects only the display of source lines. It 
does not affect the display of other debugger output, as from an EXAMINE 
command. 


The SET MARGINS command is useful for controlling the display of 
source code when, for example, the code is deeply indented or long lines 
wrap at the right margin. In such cases, you can set the left margin to 
eliminate indented space in the source display, and you can decrease the 
right margin setting (from its default value of 255) to truncate lines and 
prevent them from wrapping. 


The SET MARGINS command is useful mostly in line (noscreen) mode. 
In line mode, the SET MARGINS command affects the display of source 
lines resulting from a TYPE, EXAMINE/SOURCE, SEARCH, or STEP 
command, or when a breakpoint, tracepoint, or watchpoint is triggered. 


In screen mode, the SET MARGINS command has no effect on the display 
of source lines in a source display, such as the predefined display SRC. 
Therefore it does not affect the output of a TYPE or EXAMINE/SOURCE 
command, since that output is directed at a source display. The SET 
MARGINS command affects only the display of any source code that 
might appear in an output or DO display (for example after a STEP 
command has been executed). However, note that such source-code display 
is normally suppressed if you invoke screen mode with the keypad key 
sequence PF1-PF3, because that sequence issues the command SET STEP 
NOSOURCE in addition to SET MODE SCREEN, to eliminate redundant 
source display. 
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SET MARGINS 


By default, the debugger displays a source line beginning at character 
position 1 of the source line. This is actually character position 9 on 
your terminal screen. The first eight character positions on the screen 
are reserved for the line number and cannot be manipulated by the SET 
MARGINS command. 


If you specify a single number, the debugger sets the left margin to 1 and 
the right margin to the number specified. 


If you specify two numbers, separated with a colon, the debugger sets the 
left margin to the number on the left of the colon and the right margin to 
the number on the right. 


If you specify a single number followed by a colon, the debugger sets the 
left margin to that number and leaves the right margin unchanged. 


If you specify a colon followed by a single number, the debugger sets the 
right margin to that number and leaves the left margin unchanged. 


Related commands: SHOW MARGINS, SET STEP [NO]SOURCE. 





EXAMPLES 


DBG> SHOW MARGINS 
left margin: 1, right margin: 255 
DBG> TYPE 14 
module FORARRAY 
14; DIMENSION IARRAY (4:5,5), VECTOR(10), I3D(3,3,4) 
DBG> 


This example displays the default margin settings for a line of source code 
(1 and 255). 


DBG> SET MARGINS 39 
DBG> SHOW MARGINS 
left margin: 1, right margin: 39 
DBG> TYPE 14 
module FORARRAY 
14; DIMENSION IARRAY (4:5,5), VECTOR 
DBG> 


This example shows how the display of a line of source code changes when 
you change the right margin setting from 255 to 39. 


DBG> SET MARGINS 10:45 
DBG> SHOW MARGINS 
left margin: 10 , right margin: 45 
DBG> TYPE 14 
module FORARRAY 
14; IMENSION IARRAY (4:5,5), VECTOR(10), 
DBG> 


This example shows the display of the same line of source code after both 
margins are changed. 
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SET MARGINS 


Zl = DBG> 
DBG> 
left 
DBG> 


5 DBG> 
DBG> 
left 
DBG> 
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SET MARGINS :100 
SHOW MARGINS 
margin: 10 , right margin: 100 


This example shows how to change the right margin setting while 
retaining the previous left margin setting. 


SET MARGINS 5: 
SHOW MARGINS 
margin: 5 , right margin: 100 


This example shows how to change the left margin setting while retaining 
the previous right margin setting. 


SET MAX_SOURCE_FILES 


SET MAX SOURCE FILES 


Specifies the maximum number of source files that the debugger can keep 
open at any one time. 





FORMAT SET MAX_SOURCE FILES 1 





PARAMETERS /? 


Specifies the maximum number of source files that the debugger can keep 
open at any one time (n is a decimal integer). The value of n cannot exceed 
20. The default value is 5. 





DESCRIPTION By default, the debugger can keep five source files open at any one time. 


Opening a source file requires the use of an I/O channel, which is a limited 
system resource. Both the program and the debugger use I/O channels. To 
ensure that the debugger does not use all available I/O channels and thus 
cause the program to fail (for lack of an available I/O channel), you can 
enter the SET MAX SOURCE_FILES command to specify the maximum 
number of source files (and thus source file I/O channels) that the debugger 
can use at any one time. 


Note that the value of MAX_SOURCE_FILES does not limit the number of 
source files that the debugger can open; rather, it limits the number that 
can be kept open at any one time. Thus, if the debugger reaches this limit, 
it must close a file in order to open another one. 


Note also that setting MAX SOURCE_FILES to a very small number can 
make the debugger’s use of source files inefficient. | 


Related commands: SHOW MAX_SOURCE_FILES, (SET, SHOW, 
CANCEL) SOURCE. 





EXAMPLE 


DBG> SHOW MAX SOURCE FILES 
max source files: 5 

DBG> SET MAX SOURCE FILES 8 
DBG> SHOW MAX SOURCE FILES 
max source files: 8 

DBG> | 


In this example, the SET MAX_SOURCE_FILES 8 command enables the 
debugger to keep a maximum of eight files open at any one time. 
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SET MODE 


SET MODE 


Enables or disables a debugger mode. 





FORMAT SETMODE mode... ] 





PARAMETERS mode 


Specifies a debugger mode to be enabled or disabled. Valid keywords are 


as follows: 


DYNAMIC 


NODYNAMIC 


G_FLOAT 


NOG_FLOAT 


INTERRUPT 
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Enables dynamic mode. When dynamic mode is enabled, 
the debugger sets modules and images automatically 
during program execution so that you typically do 

not have to enter the SET MODULE or SET IMAGE 
command. Specifically, whenever the debugger interrupts 
execution (whenever the debugger prompt is displayed), 
the debugger automatically sets the module and image 
that contain the routine in which execution is currently 
suspended. If the module or image is already set, 
dynamic mode has no effect on that module or image. 
The debugger issues an informational message when 

its sets a module or image automatically. SET MODE 
DYNAMIC is the default. 


Disables dynamic mode. Because additional memory 

is allocated when a module or image is set, you might 
want to disable dynamic mode if performance becomes 

a problem (you can also free up memory by canceling 
modules and images with the CANCEL MODULE and 
CANCEL IMAGE commands). When dynamic mode is 
disabled, you must set modules and images explicitly with 
the SET MODULE and SET IMAGE commands. 


Specifies that the debugger interpret double-precision 
floating-point constants entered in expressions as 
G_FLOAT (does not affect the interpretation of variables 
declared in your program). 


Specifies that the debugger interpret doubie-precision 
floating-point constants entered in expressions as 
D_FLOAT (does not affect the interpretation of variables 
declared in your program). SET MODE NOG_FLOAT is 
the default. 


(Applies to a multiprocess debugging configuration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS). Specifies that, when program 
execution is suspended in any process, the debugger 
interrupts execution in any other processes that were 
executing images and prompts for input. SET MODE 
INTERRUPT is the default. | 


NOINTERRUPT 


KEYPAD 


NOKEYPAD 


LINE 


NOLINE 


OPERANDS[=keyword] 


NOOPERANDS 


SET MODE 


(Applies to a multiprocess debugging configuration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS). Specifies that, when program 
execution is suspended in any process, the debugger 
take the following action: 


¢ If execution was suspended because of an unhandled 
exception, the debugger interrupts execution in any 
other processes that were executing images and 
prompts for input. 


¢ If execution was suspended because of a breakpoint 
or watchpoint or the completion of a STEP command, 
the debugger lets execution proceed in any other 
processes that were executing images and does not 
display the prompt unless execution is eventually 
suspended in a// these processes. As long as 
execution continues in any process, the debugger 
does not prompt for input. In such cases, use CTRL/C 
to interrupt all processes and display the prompt. 


Enables keypad mode. When keypad mode is enabled, 
you can use the keys on the numeric keypad to 

perform certain predefined functions. Several debugger 
commands, especially useful in screen mode, are bound to 
the keypad keys (see Appendix B). You can also redefine 
the key functions with the DEFINE/KEY command. SET 
MODE KEYPAD is the default. 


Disables keypad mode. When keypad mode is disabled, 
the keys on the numeric keypad do not have predefined 
functions, nor can you assign debugger functions to those 
keys with the DEFINE/KEY command. 


Specifies that the debugger display program locations in 
terms of line numbers, if possible. SET MODE LINE is the 
default. 


Specifies that the debugger display program locations 
as routine-name + byte-offset rather than in terms of line 
numbers. 


Specifies that the EXAMINE command, when used to 
examine an instruction, display the address and contents 
of the insiruction’s operands in addition to the instruction 
and its operands. The level of information displayed 
about any nonregister operands depends on whether 
you use the keyword BRIEF or FULL. The default is 
OPERANDS=BRIEF. 


Specifies that the EXAMINE command, when used to 
examine an instruction, display only the instruction and Its 
operands. SET MODE NOOPERANDS is the default. 
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SET MODE 


SCREEN 


NOSCREEN 


SCROLL 


NOSCROLL 


SEPARATE 


NOSEPARATE 


SYMBOLIC 


NOSYMBOLIC 
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Enables screen mode. When screen mode is enabled, you 
can divide the terminal screen into rectangular regions, 
so different data can be displayed in different regions. 
Screen mode enables you to view more information more 
conveniently than the default, line-oriented, noscreen 
mode. You can use the predefined displays, or you can 
define your own. 


Disables screen mode. SET MODE NOSCREEN is the 
default. 


Enables scroll mode. When scroll mode is enabled, a 
screen-mode output or DO display is updated by scrolling 
the output line by line, as it is generated. SET MODE 
SCROLL is the default. | 


Disables scroll mode. When scroll mode is disabled, a 
screen-mode output or DO display is updated only once 
per command, instead of line by line as it is generated. 
Disabling scroll mode reduces the amount of screen 
updating that takes place and can be useful with slow 
terminals. | 


(Applies only to workstations running VWS). Specifies 
that a separate window be created for debugger input 
and output. This feature is useful when debugging screen- 
oriented programs, because it moves all debugger displays 
out of the window that contains the program’s input and 
output. The separate window is created with a height of 
24 lines and a width of 80 columns wide, emulating a 
VT-series terminal screen. 


(Applies only to workstations running VWS.) Specifies that 
no separate window be created for debugger input and 
output. SET MODE NOSEPARATE is the default. 


Enables symbolic mode. When symbolic mode is enabled, 
the debugger displays the locations denoted by address 
expressions symbolically (if possible) and displays | 
instruction operands symbolically (if possible). EXAMINE 
/NOSYMBOLIC can be used to override SET MODE 
SYMBOLIC for the duration of an EXAMINE command. 
SET MODE SYMBOLIC is the default. 


Disables symbolic mode. When symbolic mode is 
disabled, the debugger does not attempt to symbolize 
numeric addresses (it does not cause the debugger to 
convert numbers to names). This is useful if you are 
interested in identifying numeric addresses rather than 
their symbolic names (if symbolic names exist for those 
addresses). When symbolic mode is disabled, command 
processing might speed up somewhat, because the 
debugger does not need to convert numbers to names. 
EXAMINE/SYMBOLIC can be used to override SET. 
MODE NOSYMBOLIC for the duration of an EXAMINE 
command. | 


SET MODE 





DESCRIPTION _ See the parameter descriptions for details about the SET MODE command. 
The default values of these modes are the same for all languages. 


Related commands: (SHOW, CANCEL) MODE, (SET, SHOW, CANCEL) 
MODULE, (SET, SHOW, CANCEL) IMAGE, (SET, SHOW) TYPE, 
EXAMINE, DEPOSIT, EVALUATE, DEFINE/KEY, SYMBOLIZE, 
DISPLAY, SET PROMPT, (SET, SHOW, CANCEL) RADIX. 





EXAMPLE 


DBG> SET MODE SCREEN 


This command puts the debugger in screen mode. 
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SET MODULE 


SET MODULE 


Loads the symbol records of a module in the current image into the run-time 
symbol! table (RST) of that image. 





FORMAT 


SET MODULE /module-namef, ... ]] 





PARAMETERS 


module-name 

Specifies a module of the current image whose symbol records are loaded 
into the RST. Do not use the asterisk wildcard character (*). Do not 
specify a module name with /ALL. 





QUALIFIERS 


/ALL 


Specifies that the symbol records of all modules in the current image be 
loaded into the RST. Do not specify a module name with /ALL. 


/CALLS 

Sets all the modules that currently have routines on the call stack. Ifa 
module is already set, /CALLS has no effect on that module. Do not specify 
a module name with /CALLS. 


/RELATED (default) 


/NORELATED 
Note: This qualifier applies to Ada programs. 


Controls whether the debugger loads into the RST the symbol records of 
a module that is related to a specified module through a with-clause or 
subunit relationship. 


SET MODULE/RELATED loads symbol records for related modules as 
well as for those specified. This makes names declared in related modules 
visible so that you can reference them in debugger commands exactly 

as they can be referenced within the Ada source code. SET MODULE 
/NORELATED loads symbol records only for modules that are specified (no 
symbol records are loaded for related modules). 





DESCRIPTION 
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Note: The current image is either the main image (by default) 
or the image established as the current image by a previous SET 
IMAGE command. 


Symbol records must be present in the run-time symbol table (RST) if the 
debugger is to recognize and properly interpret the symbols declared in 
your program. The process by which the symbol records of a module are 
loaded into the RST is called setting a module. 


SET MODULE 


At debugger startup, the debugger sets the module containing the transfer 
address (the main program). By default, dynamic mode is enabled (SET 
MODE DYNAMIC). Therefore, the debugger sets modules (and images) 
automatically as the program executes so that you can reference symbols 
as you need them. Specifically, whenever execution is suspended, the 
debugger sets the module and image containing the routine in which 
execution is suspended. In the case of Ada programs, as a module is set 
dynamically, its related modules are also set automatically, by default, to 
make the appropriate symbols accessible (visible). 


Dynamic mode makes accessible most of the symbols you might need 
to reference. If you need to reference a symbol in a module that is not 
already set, proceed as follows: 


e Ifthe module is in the current image, use the SET MODULE command 
to set the module where the symbol is defined. 


e Ifthe module is in another image, use the SET IMAGE command 
to make that image the current image, then use the SET MODULE 
command to set the module where the symbol is defined. _ 


If dynamic mode is disabled (SET MODE NODYNAMIC), only the module 
containing the transfer address is set automatically. You must set any 
other modules explicitly. 


If you use the SET IMAGE command to establish a new current image, all 
modules previously set remain set. However, only the symbols in the set 
modules of the current image are accessible. Symbols in the set modules 
of other images are temporarily unaccessible. 


When dynamic mode is enabled, memory is allocated automatically to 
accommodate the increasing size of the RST. If dynamic mode is disabled, 
the debugger automatically allocates more memory as needed when you 
set a module or an image. Whether dynamic mode is enabled or disabled, 
if performance becomes a problem as more modules are set, use the 
CANCEL MODULE command to reduce the number of set modules. 


If a parameter in a SET SCOPE command designates a program location 
in a module that is not already set, the SET SCOPE command sets that 
module. 


Related commands: (SHOW, CANCEL) MODULE, SET MODE 
[NO]DYNAMIC, (SET, SHOW, CANCEL) IMAGE. 





EXAMPLES 
DBG> SET MODULE SUB1 


This command sets module SUB1 (loads the symbol records of module 
SUB1 into the RST). 
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SET MODULE 


DBG> SET IMAGE SHARE3 
DBG> SET MODULE MATH 
DBG> SET BREAK %LINE 31 


In this example, the SET IMAGE command makes shareable image 
SHARE3 the current image. The SET MODULE command sets module 
MATH in image SHARE3. The SET BREAK command sets a breakpoint 
on line 31 of module MATH. 


DBG> SHOW MODULE/SHARE 


module name symbols language size 
FOO yes MACRO 432 
MAIN no FORTRAN 280 
SHARESDEBUG no Image 0 
SHARESLIBRTL no Image 0 
SHARESMTHRTL no Image 0 
SHARES SHARE1 no Image 0 
SHARES SHARE2 no Image 0 
total modules: 17. bytes allocated: 162280. 


DBG> SET MODULE SHARESSHARE2 
DBG> SHOW SYMBOL * IN SHARESSHARE2 


In this example, the SHOW MODULE/SHARE command identifies all 

of the modules in the current image and all of the shareable images 

(the names of the shareable images are prefixed with "SHARE$"). The 
command SET MODULE SHARE$SHARE2Z sets the shareable image 
module SHARE$SHARE2. The SHOW SYMBOL command identifies 
any universal symbols defined in the shareable image SHARE2. See the 
description of the /SHARE qualifier of the SHOW MODULE command for 
more information. 
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SET OUTPUT 


SET OUTPUT 


Enables or disables a debugger output option. 





FORMAT SET OUTPUT output-option[, ... ] 





PARAMETERS output-option — 
Specifies an output option to be enabled or disabled. Valid keywords are 


as follows: 
LOG 


NOLOG 


SCREEN_LOG 


NOSCREEN_LOG 
TERMINAL 
NOTERMINAL 


VERIFY 


NOVERIFY 


Specifies that debugger input and output be recorded in a log 
file. If you specify the log file by the SET LOG command, the 
debugger writes to that file; otherwise, by default the debugger 
writes to SYS$DISK[]:DEBUG.LOG. 


Specifies that debugger input and output not be recorded in a 
log file. NOLOG is the default. 


Specifies that, while in screen mode, the screen contents be 
recorded in a log file as the screen is updated. To log the 
screen contents you must also specify SET OUTPUT LOG. See 
the description of the LOG option regarding specifying the log 
file. 


Specifies that the screen contents, while in screen mode, not be 
recorded in a log file. NOSCREEN_LOG is the default. 


Specifies that debugger output be displayed at the terminal. 
TERMINAL is the default. 


Specifies that debugger output, except for diagnostic messages, 
not be displayed at the terminal. 


Specifies that the debugger echo, on the current output device, 
each input command string that it is executing from a command 
procedure or DO clause. The current output device is by default 
SYS$OUTPUT, the terminal, but can be redefined with the 
logical name DBG$SOUTPUT. 


Specifies that the debugger not display each input command 
string that it is executing from a command procedure or DO 
clause. NOVERIFY is the default. 





DESCRIPTION Debugger output options control the way in which debugger responses to 
commands are displayed and recorded. See the parameter descriptions for 
details about the SET OUTPUT command. 


Related commands: SHOW OUTPUT, (SET, SHOW) LOG, SET MODE 
SCREEN, @file-spec, (SET, SHOW) ATSIGN. 
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SET OUTPUT 





EXAMPLE 


DBG> SET OUTPUT VERIFY, LOG, NOTERMINAL 


This command specifies that the debugger take the following action: 


e Output each command string that it is executing from a command 
procedure or DO clause (VERIFY). 


¢ Record debugger output and user input in a log file (LOG). 


e Not display output at the terminal, except for diagnostic messages 
(NOTERMINAL). 
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SET PROCESS 


SET PROCESS 


Note: This command applies to a multiprocess debugging configuration 
(when DBG$PROCESS has the value MULTIPROCESS). 


Establishes the visible process, modifies characteristics of one or more 
processes, or enables/disables dynamic process setting. 





FORMAT SET PROCESS /[process-specf, ... |] 





PARAMETERS Pprocess-spec 


Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name 


[%PROCESS_NAME] "process-name" 


%PROCESS_PID process_id 
%PROCESS_NUMBER process-number (or 
%PROC process-number) 


process-group-name 


%NEXT_PROCESS 


%PREVIOUS_PROCESS 


%VISIBLE_PROCESS 


The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

The VMS process name, if that 

name contains space or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


The VMS process identification number 
(PID, a hexadecimal number). 


The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 


A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. 


The process after the visible process in 
the debugger’s circular process list. 


The process previous to the visible 
process in the debugger’s circular 
process list. 


The process whose call stack, register 

set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk wildcard character (*) to specify all 


processes. 
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SET PROCESS 





QUALIFIERS 
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/ALL 


Applies the SET PROCESS command to all processes. Do not specify a 
process with this qualifier. Do not specify /[NOJDYNAMIC, or /VISIBLE 
with /ALL. 


/DYNAMIC (default) 
/NODYNAMIC 


Controls whether dynamic process setting is enabled or r disabled. When 
dynamic process setting is enabled (DYNAMIC), whenever the debugger 
suspends execution and displays its prompt, the process in which execution 
is suspended becomes the visible process automatically. When dynamic 
process setting is disabled ((NODYNAMIC), the visible process remains 
unchanged until you specify another process with the SET PROCESS 
/VISIBLE command. 


Do not specify a process with /[NOJDYNAMIC. Do not specify /ALL, 
/INOJHOLD, or /VISIBLE with /INO]DYNAMIC. 


/HOLD 

/NOHOLD 

/HOLD puts a specified process on hold. This prevents images in that 
process from executing when you enter a GO, STEP, or CALL command, 


unless the process is the visible process. A hold condition i in the visible 
process is ignored. 


The /NOHOLD qualifier releases a specified process from a hold condition. 
This permits images in that process to execute when you enter a GO, 
STEP, or CALL command, regardless of which process is the visible 
process. 


The behavior described also applies when you use the DO command to 
broadcast a GO, STEP, or CALL command to specific processes. 


If no process is specified, /HOLD puts the visible process on hold, and 
/NOHOLD releases the visible process from the hold condition. 


See the descriptions of the GO, STEP, CALL, EXIT, and QUIT commands 
for the effects of these commands on processes that have or have not been 
put on hold. 


Do not specify [NO]DYNAMIC with /[NOJHOLD. 

/VISIBLE | 

Makes the specified process the visible process. This switches your 
debugging context to the specified process, so that symbol lookups and 


the setting of breakpoints, and so on, are done in the context of that 
process. You must specify one, and only one, process. 


If you do not specify /VISIBLE, it is assumed by default. 
Do not specify /ALL, or /[NO]DYNAMIC with /VISIBLE. 


SET PROCESS 


DESCRIPTION The SET PROCESS command establishes the visible process or modifies 
characteristics of one or more processes. 





By default, commands are executed in the context of the visible process. 
The visible process is the process that is your current debugging context. 
Symbol lookups and the setting of breakpoints, and so on, are done in the 
context of the visible process. 


The DO command enables you to execute commands in the context of 
specific processes or of all processes. The DO command is equivalent to 
entering a SET PROCESS/VISIBLE command for each process specified 
(or for all processes, if no process is specified with the DO command) and 
then entering the specified commands. 


Dynamic process setting is enabled by default and is controlled with the 
/[NOJDYNAMIC qualifier. When dynamic process setting is enabled, 
whenever the debugger suspends program execution and displays its 
prompt, the process in which execution is suspended becomes the visible 
process automatically. 


Related commands: SHOW PROCESS, DO, GO, STEP, CALL, EXIT, 
QUIT. 


EXAMPLE 


DBG_1> SET PROCESS/HOLD/ALL 
DBG 1> SHOW PROCESS/ALL 





Number Name Hold State Current PC 

: 1 TEST _X YES step PROG\%SLINE 50 
2 TEoT. Y YES break PROG\SLINE 71 

DBG_1> 


The command SET PROCESS/HOLD/ALL puts all processes on hold. This 
is confirmed in the SHOW PROCESS/ALL display. 


DBG_1> SET PROCESS/NOHOLD %VISIBLE PROCESS 
DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 

: 1 TEST _X step PROG\SLINE 50 
2 TEST _Y YES break PROG\SLINE 71 

DBG _1> | 


The command SET PROCESS/NOHOLD %VISIBLE_PROCESS releases 
the visible process from the hold condition. This is confirmed in the SHOW 
PROCESS/ALL display. 


DBG_1> SET PROCESS TEST _Y 
DBG_2> SHOW PROCESS 


Number Name Hold State Current PC 
* 2 TEST ¥ YES break PROG\SLINE 71 
DBG 2> 


The command SET PROCESS TEST _Y makes process TEST _Y the visible 
process. The command SHOW PROCESS displays information about the 
visible process by default. 
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SET PROCESS 


DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> DO (EXAMINE X; STEP) 
For %PROCESS NUMBER 1 


MAIN PROG\X: 78 
For SPROCES S_ NUMBER zZ 
TEST\X: 29 
stepped to MAIN PROG\SLINE 26 in %PROCESS NUMBER 1 
26% K=K+4+1 
DBG_1> 


The command SET PROCESS/HOLD/ALL puts all processes on hold. The 
DO command broadcasts the commands EXAMINE X and STEP to all 
processes (processes 1 and 2, in this example). The STEP command is 
executed in the context of process 1, because a hold condition in the visible 


process is ignored. Because process 2 is on hold, execution is inhibited in 
that process. 
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SET PROMPT 


SET PROMPT 


Changes the debugger prompt string to your personal preference. 





FORMAT 


SET PROMPT §[prompt-parameter] 





PARAMETERS 


prompt-parameter 

Specifies the new prompt string. If the string contains spaces, semicolons 
(;), or lowercase characters, you must enclose it in quotation marks (") or 
apostrophes ('). If you do not specify a string, the current prompt string 
remains unchanged. 


By default, the prompt string is DBG> for a nonmultiprocess debugging 
configuration (when the logical name DBG$PROCESS is undefined or has 
the value DEFAULT). 


By default, for a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS), the prompt string 
consists of a process-independent prefix (specified by prompt-parameter) 
and a process-specific suffix (specified by the /[NOJSUFFIX qualifier). The 
suffix changes automatically as the visible process changes. 





QUALIFIERS 


/SUFFIX[=process-identifier-type] 
/NOSUFFIX 


Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


The /SUFFIX qualifier enables "dynamic prompt setting". As a result, 
the prompt string includes a process-specific suffix that automatically 
identifies the visible process. This is the default behavior. 


The /NOSUFFIX qualifier disables dynamic prompt setting. As a result, 
the prompt string does not include a process-specific suffix and does not 
change when another process becomes the visible process. 


When you invoke the debugger with the RUN command to debug a 
multiprocess program, the prompt string is DBG_1> by default. This 
indicates that dynamic prompt setting is enabled and that the visible 
process is process 1 (the first process connected to the debugger). You can 
control the process-specific prompt-string suffix by specifying one of the 
following process-identifier-type keywords with the /SUFFIX qualifier: 


PROCESS_NAME The prompt-string suffix is the VMS process name. 


PROCESS_NUMBER _ The prompt-siring suffix is the process number (as shown in 
a SHOW PROCESS display). This is the default. 


PROCESS_PID The prompi-string suffix is the VMS process identification 
number (PID). 
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SET PROMPT 


The following table illustrates the possible kinds of prompt strings for a 
multiprocess debugging configuration. Note that the entire prompt string 
depends on the prompt-parameter command parameter (which controls the 
process-independent prefix), and on the values of /[NOJSUFFIX and the 
process-identifier-type keyword (which control the process-specific suffix). 


prompt-parameter 

(prefix) Qualifier and Keyword (suffix) Resulting Prompt String 
none none unchanged 

none /NOSUFFIX DBG> 

none /SUFFIX DBG_process-numbers ' 
none /SUFFIX=PROCESS_NAME process-name> 

none /SUFFIX=PROCESS_NUMBER process-number> 

none /SUFFIX=PROCESS_PID pid> 

XYZ_ /NOSUFFIX XYZ_> 

XYZ_ /SUFFIX XYZ_process-number> 
XYZ_ /SUFFIX=PROCESS_NAME XYZ '_process-name> 
XYZ_ /SUFFIX=PROCESS_NUMBER XYZ_process-number> 


XYZ_ /SUFFIX=PROCESS_PID XYZ_pid> 


'The default prompt for a multiprocess debugging configuration is DBG_process-numbers, which 
is equivalent to entering the following command: | 
DBG> SET PROMPT/SUFFIX=PROCESS_ NUMBER "DBG_" 


/POP 
/NOPOP (default) 


Note: This qualifier applies only to workstations running VWS. 


The /POP qualifier causes the debugger window to pop over other windows 
and become attached to the keyboard when the debugger prompts for 
input. The /NOPOP qualifier disables this behavior (the debugger window 
is not popped over other windows and is not attached to the keyboard 
automatically when the debugger prompts for input). 


If you do not specify /POP or /NOPOP, the prompt behavior is set to 
/NOPOP 





DESCRIPTION 
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The SET PROMPT command enables you to tailor the debugger prompt 
string to your individual preference. 

If you are using a multiprocess debugging configuration (when the logical 
name DBG$PROCESS has the value MULTIPROCESS), the /[NO]JSUFFIX 
qualifier enables you to specify a process-specific prompt-string suffix. 

If you are using the debugger at a workstation, the /[NOJPOP qualifier 
enables you to control whether the debugger window is popped over other 
windows whenever the debugger prompts for input. 


Related commands: (SET, SHOW) PROCESS. 


SET PROMPT 





EXAMPLES 


DBG> SET PROMPT "S " 

$ SET PROMPT "d bg: " 
dbg: SET PROMPT "DBG> " 
DBG> 


The successive SET PROMPT commands change the debugger prompt 
from “DBG>” to “$”, to “d b g :”, then back to “DBG>”. 


DBG_1> SET PROMPT/NOSUFFIX "dbg> " 

dbg> SET PROMPT/SUFFIX 

DBG_1> SET PROMPT/SUFFIX=PROCESS NUMBER "xyz_" 
xyZ_1> SET PROMPT/SUFFIX=PROCESS NAME 

SMITH> SET PROMPT/SUFFIX=PROCESS NAME "John " 
John SMITH> SET PROMPT/SUFFIX=PROCESS PID 
20800E4D> 7 


The successive SET PROMPT commands show the effect of the 


/[NO]SUFFIX qualifier and the prompt-parameter string for multiprocess 
programs. 
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SET RADIX 


SET RADIX 


Establishes the radix for the entry and display of integer data. When used with 
/OVERRIDE, causes all data to be displayed as integer data of the specified 
radix. 














FORMAT SET RADIX __ radix 
PARAMETERS radix 
Specifies the radix to be established. Valid keywords are as follows: 
BINARY Sets the radix to binary. 
DECIMAL Sets the radix to decimal. This is the default for all languages 
except BLISS and MACRO. 
DEFAULT Sets the radix to the language default. 
OCTAL Sets the radix to octal. 
HEXADECIMAL Sets the default radix to hexadecimal. This is the default for BLISS 
and MACRO. 
QUALIFIERS ANPUT 
Sets only the input radix (the radix for entering integer data) to the 
specified radix. 
/OUTPUT 
Sets only the output radix (the radix for displaying integer data) to the 
specified radix. 
/OVERRIDE 
Causes all data to be displayed as integer data of the specified radix. 
DESCRIPTION = The current radix setting influences how the debugger interprets and 
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displays integer data in the following contexts: 


¢ Integer data that you specify in address expressions or language 
expressions. 


e Integer data that is displayed by the commands EXAMINE and 
EVALUATE. 


The default radix for both data entry and display is decimal for all 
languages except BLISS and MACRO. It is hexadecimal for BLISS and 
MACRO. 


The SET RADIX command enables you to specify a new radix for data 
entry or display (the input radix and output radix, respectively). 


SET RADIX 


If you do not specify a qualifier, the SET RADIX command changes both 
the input and output radix. If you specify the INPUT or /OUTPUT 
qualifier, the command changes the input or output radix, respectively. 


If you specify the /OVERRIDE qualifier, the SET RADIX command changes 
only the output radix but causes all data (not just data that has an integer 
type) to be displayed as integer data of the specified radix. 


Note that, except when used with the /OVERRIDE qualifier, the SET 
RADIX command does not affect the interpretation or display of noninteger 
values (such as real or enumeration type values). 


The EVALUATE, EXAMINE, and DEPOSIT commands have radix 
qualifiers (/BINARY, /HEXADECIMAL, and so on) that enable you 

to override, for the duration of that command, any radix previously 
established with the SET RADIX or SET RADIX/OVERRIDE command. 


You can also use the built-in symbols BIN, DEC, %HEX, and %OCT in 
address expressions and language expressions to specify that an integer 
literal that follows should be interpreted in binary, decimal, hexadecimal, 
or octal radix, respectively (see Appendix D). 


Related commands: (SHOW, CANCEL) RADIX, (SET, SHOW, CANCEL) 
MODE, EVALUATE, EXAMINE, DEPOSIT. 





EXAMPLES 


DBG> SET RADIX HEX 


This command sets the radix to hexadecimal. This means that, by default, 
integer data is interpreted and displayed in hexadecimal radix. 


DBG> SET RADIX/INPUT OCT 


This command sets the radix for input to octal. This means that, by 
default, integer data that is entered is interpreted in octal radix. 


DBG> SET RADIX/OUTPUT BIN 


This command sets the radix for output to binary. This means that, by 
default, integer data is displayed in binary radix. 


DBG> SET RADIX/OVERRIDE DECIMAL 


This command sets the override radix to decimal. This means that, by 
default, all data (not just data that has an integer type) is displayed as 
decimal integer data. 
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SET SCOPE 


Establishes how the debugger looks up symbols (variable names, routine 
names, line numbers, and so on) when a path name prefix is not specified. 





FORMAT — ~SETSCOPE Jocation/, ...] 





PARAMETERS _/ocation 
| Denotes a program region (scope) to be used for the interpretation of 
symbols that you specify without a path name prefix. A location can be 
any of the following, unless you specify /CURRENT or /MODULE (see the 
qualifier descriptions): 


path name prefix Specifies the scope denoted by the path name prefix. A path 

name prefix consists of the names of one or more nesting 
program elements (module, routine, block, and so on), with 
each name separated by a backslash character (\). When 
a path name prefix consists of more than one name, list a 
nesting element to the left of the \ and a nested element 

to the right of the \. A common n path name prefix format is 
module\ routine\ block\. 


If you specify only a module name and that name is the 
same as the name of a routine, use the /MODULE qualifier; 
otherwise, the debugger assumes that you are specifying the 
routine. 


n Specifies the scope denoted by the routine which is n 
levels down the call stack (n is a decimal integer). A scope 
specified by an integer changes dynamically as the program 
executes. The value 0 denotes the routine that is currently 
executing, the value 7 denotes the caller of that routine, and 
so on down the call stack. The default scope search list is 
0,1,2,...,n, where nis the number of calls in the cail stack. 


\ Specifies the global scope—that is, the set of all program 
locations in which a global symbol is known. The definition 
of a global symbol and the way it is declared depends on the 
language. 


When you specify more than one location parameter, you establish a scope 
search list. If the debugger cannot interpret the symbol using the first 
parameter, it uses the next parameter, and continues using parameters 
in order of their specification until it successfully interprets the symbol or 
until it exhausts the parameters specified. 





QUALIFIERS /CURRENT 
Establishes a scope search list that is like the default search list 


(0,1,2, ...,n) but starts at the numeric scope specified as the command 
parameter. Scope 0 is the PC scope, and n is the number of calls i in the 
call stack. , 
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SET SCOPE 


When using SET SCOPE/CURRENT, note the following conventions and 
behavior: 


¢ The default scope search list must be in effect when the command is 
entered. To restore the default scope search list, enter the command 
CANCEL SCOPE. 


¢ The command parameter specified must be one (and only one) decimal 
integer from 0 to 7. 


¢ In screen mode, the command updates the predefined source and 
instruction displays SRC and INST, respectively, to show the routine 
on the call stack in which symbol searches are to start. 


¢ The default scope search list is restored when program execution is 
resumed. 


/MODULE 


Indicates that the name specified as the command parameter is a module 
name and not a routine name. You need to use /(MODULE only if you 
specify a module name as the command parameter and that module name 
is the same as the name of a routine. 





DESCRIPTION 


By default, the debugger looks up a symbol specified without a path 
name prefix according to the scope search list 0,1,2, ...,n, where n is the 
number of calls in the call stack. This scope search list is based on the 
current PC value and changes dynamically as the program executes. The 
default scope search list specifies that a symbol lookup such as "EXAMINE 
X" first looks for X in the routine that is currently executing (scope 0); if 
no X is visible there, the debugger looks in the caller of that routine (scope 
1), and so on down the call stack; if X is not found in scope n, the debugger 
searches the rest of the run-time symbol table (RST)—that is, all set 
modules and the global symbol table (GST), if necessary. 


In most cases, this default scope search list enables you to resolve 
ambiguities in a predictable, natural way that is consistent with language 
rules. But if you cannot access a symbol that is defined multiple times, 
use either of the following techniques: 


e Specify the symbol with a path name prefix. The path name 
prefix consists of any nesting program units (for example, 
module \ routine \ block) that are necessary to specify the symbol 
uniquely. For example: 

DBG> EXAMINE MOD4\ROUT3\X 
DBG> TYPE MOD4\27 


¢ Establish a new default scope (or a scope search list) for symbol lookup 
by means of the SET SCOPE command. You can then specify the 
symbol without using a path name prefix. For example: 
DBG> SET SCOPE MOD4\ROUT3 


DBG> EXAMINE X 
DBG> TYPE 27 


The SET SCOPE command is useful in those cases where otherwise you 
would need to use a path name repeatedly to specify symbols. 
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SET SCOPE 


To restore the default scope search list, use the CANCEL SCOPE 
command. 


When the default scope search list is in effect, you can use the command 
SET SCOPE/CURRENT to specify that symbol searches start at a numeric 
scope other than scope 0, relative to the call stack (for example, scope 2). 


When you use the SET SCOPE command, the debugger searches only the 
program locations you specify explicitly, unless you use the /CURRENT 
qualifier. Also, the scope or scope search list established with a SET 
SCOPE command remains in effect until you restore the default scope 
search list or enter another SET SCOPE command. However, if you use 
the /CURRENT qualifier, the default scope search list is restored whenever 
program execution is resumed. 


The SET SCOPE command updates a screen-mode source or instruction 
display only if the command is used with the /CURRENT qualifier, 


If a name you specify in a SET SCOPE command is the name of both a 
module and a routine, the debugger sets the scope to the routine. In such 
cases, use the command SET SCOPE/MODULE if you want to set the 
scope to the module. 


If you specify a module name in a SET SCOPE command, the debugger 
"sets" that module if it is not already set. However, if you want only to set 
a module, use the SET MODULE command rather than the SET SCOPE 
command, to avoid the possibility of disturbing the current scope search 
list. 


Related commands: (SHOW, CANCEL) SCOPE, CANCEL ALL, SET 
MODULE, SHOW SYMBOL, SYMBOLIZE, SEARCH, TYPE. 





EXAMPLES 


DBG> EXAMINE Y 


SDEBUG-W-NOUNIQUE, symbol ’Y’ is not unique 
DBG> SHOW SYMBOL Y 

data CHECK IN\Y 

data INVENTORY\COUNT\Y 
DBG> SET SCOPE INVENTORY \COUNT 


DBG> EXAMINE Y 


INVENTORY\COUNT\Y: 347.15 


DBG> 
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In this example, the first EXAMINE Y command indicates that symbol 
Y is defined multiple times and cannot be resolved from the current 
scope search list. The SHOW SYMBOL command displays the different 
declarations of symbol Y. The SET SCOPE command directs the debugger 
to look for symbols without path name prefixes in routine COUNT of 
module INVENTORY. The subsequent EXAMINE command can now 
interpret Y unambiguously. 


SET SCOPE 


DBG> CANCEL SCOPE 
DBG> SET SCOPE/CURRENT 1 


In this example, the CANCEL SCOPE command restores the default scope 
search list (0,1,2, ...,n). The SET SCOPE/CURRENT command then 
changes the scope search list to 1,2, ... ,n, so that symbol searches start 
with scope 1—that is, with the caller of the routine in which execution 

is currently suspended. The predefined source and instruction displays 
SRC and INST, respectively, are updated and now show the source and 
instructions for the caller of the routine in which execution is suspended. 


DBG> SET SCOPE 1 
DBG> EXAMINE %R5 


In this example, the SET SCOPE command directs the debugger to look 
for symbols without path name prefixes in scope 1—that is, in the caller 
of the routine in which execution is suspended. The EXAMINE command 
then displays the value of register R5 in the caller routine. Note that the 
SET SCOPE command, when used without the /CURRENT qualifier, does 
not update any source or instruction display. 


DBG> SET SCOPE 0, STACKS\R2, SCREEN 


This command directs the debugger to look for symbols without path name 
prefixes according to the following scope search list. First the debugger 
looks in the PC scope (denoted by "0"). If the debugger cannot find a 
specified symbol in the PC scope, it then looks in routine R2 of module 
STACKS. If necessary, it then looks in module SCREEN. If the debugger 
still cannot find a specified symbol, it looks no further. 


DBG> SHOW SYMBOL X 


data ALPHA\X ! global X 

data ALPHA\BETA\X ! local X 

data X (global) ! same as ALPHA\X 
DBG> SHOW SCOPE 

scope: 0 [ = ALPHA\BETA ] 


DBG> SYMBOLIZE X 

address ALPHA\BETA\$S%RO0: 
ALPHA\BETA\X 

DBG> SET SCOPE \ 

DBG> SYMBOLIZE X 

address 00000200: 
ALPHA\X 

address 00000200: (global) 
X 

DBG> 


In this example, the SHOW SYMBOL command indicates that there are 
two declarations of the symbol X—a global ALPHA\X (shown twice) and a 
local ALPHA\ BETA\X. Within the current scope, the local declaration of 
X (ALPHA\ BETA\X) is visible. After the scope is set to the global scope 
(SET SCOPE \), the global declaration of X is made visible. 
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SET SEARCH 


Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) for 
the SEARCH command. 





FORMAT 








SET SEARCH = search-default/,... ] 
PARAMETERS _ search-default 
| Specifies a default to be established for the SEARCH eoihiand: Valid 
keywords (which correspond to SEARCH command qualifiers) are as 
follows: 
ALL Subsequent SEARCH commands are treated as SEARCH/ALL, 
rather than SEARCH/NEXT. | 
IDENTIFIER Subsequent SEARCH commands are treated as SEARCH 
/IDENTIFIER, rather than SEARCH/STRING. 
NEXT Subsequent SEARCH commands are treated as SEARCH/NEXT, 
rather than SEARCH/ALL. This is the default. 
STRING Subsequent SEARCH commands are treated as SEARCH/STRING, 
rather than SEARCH/IDENTIFIER. This is the default. 
DESCRIPTION = The SET SEARCH command establishes default qualifiers for subsequent 
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SEARCH commands. The parameters that you specify in the SET 
SEARCH command have the same names as the SEARCH command 
qualifiers. SEARCH command qualifiers determine whether the SEARCH 
command: (1) searches for all occurrences (ALL) of a string or only the 
next occurrence (NEXT); and (2) displays any occurrence of the string 
(STRING) or only those occurrences in which the string is not bounded on 
either side by a character that can be part of an identifier 1 in the current 
language (IDENTIFIER). 


You can override the current SEARCH default for the duration of a 
single SEARCH command by specifying other qualifiers. Use the SHOW 
SEARCH command to identify the current SEARCH defaults. 


Related commands: SEARCH, SHOW SEARCH, (SET, SHOW) 
LANGUAGE. 


SET SEARCH 





EXAMPLE 


DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 
DBG> SET SEARCH IDENTIFIER 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 

DBG> SHOW SEARCH 


search settings: search for all occurrences, as an identifier 
DBG> 


In this example, the SET SEARCH IDENTIFIER command directs the 
debugger to search for an occurrence of the string in the specified range 
but display the string only if it is not bounded on either side by a character 
that can be part of an identifier in the current language. 


The SET SEARCH ALL command directs the debugger to search for (and 
display) all occurrences of the string in the specified range. 
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SET SOURCE 


SET SOURCE 


Specifies where the debugger is to search for source files that have been 
moved to another directory after being compiled. 





FORMAT 


SET SOURCE  dilrectory-spec/,... | 





PARAMETERS 


directory-spec 

Specifies any part of a VMS file specification (typically a device/directory) 
that the debugger is to use by default when searching for a source file. For 
any part of a full file specification that you do not supply, the debugger 
uses the file specification stored in the module’s symbol record—that is, 
the file specification that the source file had at compile time. 


If you specify more than one directory in a single SET SOURCE command, 
you create a source directory search list (you can also specify a search 
list logical name that is defined at your process level). In this case, the 
debugger locates the source file by searching the first directory specified, 
then the second, and so on, until it either locates the source file or 
exhausts the list of directories. 





QUALIFIERS 


/EDIT 
Note: This qualifier applies mainly to Ada programs. 


Specifies that the directory search list is used to locate source files for 
editing when you use the EDIT command. 


/MODULE=module-name 


Specifies that the directory search list is used to locate source files only for 
the specified module. 





DESCRIPTION 
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By default, the debugger expects a source file to be in the same directory 
it was in at compile time (the debugger also checks that the creation 
and revision date and time of a source file match the information in the 
debugger’s symbol table). If a source file has been moved to a different 
directory since compile time, use the SET SOURCE command to specify a 
source directory search list. 


When a source file is moved to another directory, the version number of 
the source file might change. To locate the correct version of the source file 
in the event that a version number was not specified in the directory-spec 
parameter, the debugger inserts the match-all asterisk wildcard character 
(*) in the version number field of the new file specification. Therefore, 

all versions of the moved source file are searched until the correct version 
is located. The correct version of the source file is the version that has 
the same creation or revision date and time, the same file size, the same 
record format, and the same file organization as the original compile-time 
source file. 


SET SOURCE 


If the debugger does not find the correct version, it uses the file that has 
the closest revision date and time (if such a file exists in that directory) 

and issues a message such as the following when first displaying source 

code: 


%DEBUG-I-NOTORIGSRC, original version of source file not found 
file used is WORK: [JONES.PROG3]PRG.FOR;14 


If you enter the SET SOURCE command without the /(MODULE=module- 
name qualifier, the debugger uses the specified directory search list to 
locate source files for all modules that were not mentioned in a previous 
SET SOURCE/MODULE=module-name command. 


See the qualifier descriptions for an explanation of their effects. 


The /EDIT qualifier is needed when the files used for the display of source 
code are different from the files to be edited by means of the EDIT 
command. This is the case with Ada programs. For Ada programs, the 
(SET, SHOW, CANCEL) SOURCE commands affect the search of files used 
for source display (the "copied" source files in Ada program libraries); the 
(SET, SHOW, CANCEL) SOURCE/EDIT commands affect the search of the 
source files you edit when using the EDIT command. If you use /MODULE 
with /EDIT, the effect of /EDIT is further qualified by (MODULE. 


A full VMS file specification consists of the following fields: 
node::device:[directory]file-name.file-type;version-number 


If the full file specification of a source file exceeds 231 characters, the 
debugger cannot locate the file. You can work around this problem by 
first defining a logical name "X" (at DCL level) to expand to your long file 
specification, and then using the command "SET SOURCE X". 


Related commands: (CANCEL, SHOW) SOURCE, (CANCEL, SHOW) 
MAX SOURCE_FILES. 





EXAMPLES 


DBG> SHOW SOURCE 

no directory search list in effect 

DBG> SET SOURCE [PROJA], [PROJB],USERS: [PETER.PROJC] 
DBG> SHOW SOURCE 

source directory search list for all modules: 


USERS: [PETER.PROJC] 


In this example, the SET SOURCE command specifies that 
the debugger should search directories [PROJA], [PROJB], and 
USER$:[PETER.PROJC], in that order, for source files. 
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SET SOURCE 


DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2: [PROUD] 
DBG> SHOW SOURCE 


source directory search list for COBOLTEST: 
[] 
DISKS$2: [PROJD] 
source directory search list for all other modules: 
[PROJA] 
[PROJB] 
USERS: [PETER.PROJC] 
DBG> 


In this example, the SET SOURCE command specifies that the debugger 
should search the current default directory ({]) and DISK$2:[PROJD], 
in that order, for source files to use with the module COBOLTEST. 

The SHOW SOURCE command displays the search lists established in 
examples 1 and 2. 
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SET STEP 


SET STEP 


Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP 


command. 





FORMAT SETSTEP step-defaultf, ... ] 





PARAMETERS _ step-default 
Specifies a default to be established for the STEP command. Valid 
keywords (which correspond to STEP command qualifiers) are as follows: 


BRANCH 
CALL 
EXCEPTION 


INSTRUCTION 


INTO 


JSB 


NOJSB 


LINE 


OVER 


RETURN 


Subsequent STEP commands are treated as STEP/BRANCH (step 
to the next branch instruction). 


Subsequent STEP commands are treated as STEP/CALL (step to 
the next call instruction). 


Subsequent STEP commands are treated as STEP/EXCEPTION 
(step to the next exception). 


Subsequent STEP commands are treated as STEP/INSTRUCTION 
(step to the next instruction). You can also specify one or more 
instructions (INSTRUCTION=(opcode-list)). The debugger then 
steps to the next instruction that is in the specified list. If you 
specify a vector instruction, do not include an instruction qualifier 
(/U, /V, /M, /0, or /1) with the instruction mnemonic. 


Subsequent STEP commands are treated as STEP/INTO (step into 
called routines) rather than STEP/OVER (step over called routines). 
When INTO is in effect, you can qualify the types of routines to step 
into by means of the [NO]JSB, [NO]JSHARE, and [NO]SYSTEM 
parameters, or by using the STEP/[NO|JJSB, STEP/[NO]SHARE, 
and STEP/[NO]SYSTEM command/qualifier combinations (the latter 
three take effect only for the immediate STEP command). 


lf INTO is in effect, subsequent STEP commands are treated as 
STEP/INTO/JSB (step into routines called by a JSB instruction as 
well as those called by a CALL instruction). This is the default for 
all languages except DIBOL. 


If INTO is in effect, subsequent STEP commands are treated as 
STEP/INTO/NOUSB (step over routines called by a JSB instruction, 
but step into routines called by a CALL instruction). This is the 
default for DIBOL. 


Subsequent STEP commands are treated as STEP/LINE (step to 
the next line). This is the default for all languages. 

Subsequent STEP commands are treated as STEP/OVER (step 
over all called routines) rather than STEP/INTO (step into called 
routines). SET STEP OVER is the default. 


Subsequent STEP commands are treated as STEP/RETURN (step 
to the RET instruction of the routine that is currently executing— 
that is, up to the point just prior to transferring control back to the 
calling routine). 
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SET STEP 


SHARE 


NOSHARE 


SILENT 


NOSILENT 


SOURCE 


NOSOURCE 


SYSTEM 


NOSYSTEM 


VECTOR _ 
INSTRUCTION 


lf INTO is in effect, subsequent STEP commands are treated as 
STEP/INTO/SHARE (step into called routines in shareable images 
as well as into other called routines). This is the default. 


If INTO is in effect, subsequent STEP commands are treated as 
STEP/INTO/NOSHARE (step over called routines in shareable 
images, but step into other routines). 


Subsequent STEP commands are treated as STEP/SILENT (after a 
step, do not display the "stepped to ... " message or the source 
line for the current location). 


Subsequent STEP commands are treated as STEP/NOSILENT 
(after a step, display the "stepped to ... " message). This is the 
default. 


Subsequent STEP commands are treated as STEP/SOURCE 
(after a step, display the source line for the current location). 
Aiso, subsequent SET BREAK, SET TRACE, and SET WATCH 
commands are treated as SET BREAK/SOURCE, SET TRACE 
/SOURCE, and SET WATCH/SOURCE, respectively (at a 
breakpoint, tracepoint, or watchpoint, display the source line for 
the current location). This is the default. 


Subsequent STEP commands are treated as STEP/NOSOURCE 
(after a step, do not display the source line for the current location). 
Also, subsequent SET BREAK, SET TRACE, and SET WATCH 
commands are treated as SET BREAK/NOSOURCE, SET TRACE 
/NOSOURCE, and SET WATCH/NOSOURCE, respectively (at a 
breakpoint, tracepoint, or watchpoint, do not display the source line 
for the current location). 


If INTO is in effect, subsequent STEP commands are treated as 
STEP/INTO/SYSTEM (step into called routines in system space (P1 
space) as well as into other called routines). This is the default. 


If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/NOSYSTEM (step over called routines in system 
space, but step into other routines). 


(Applies to vectorized programs). Subsequent STEP commands 
are treated as STEP/VECTOR_INSTRUCTION (step to the next 
vector instruction). 





DESCRIPTION 


CD-180 


The SET STEP command establishes default qualifiers for subsequent 
STEP commands. The parameters that you specify in the SET STEP 
command have the same names as the STEP command qualifiers. The 
following parameters affect where the STEP command suspends execution 


after a step: 


BRANCH 


CALL 


EXCEPTION 
INSTRUCTION[=(opcodel, ... ])] 


LINE 


RETURN 


VECTOR_INSTRUCTION 


SET STEP 


The following parameters affect what output is seen when a STEP 
command is executed: 


[NO]SILENT 
[NOJSOURCE 


The following parameters affect what happens at a routine call: 


INTO 
[NO]JSB 
OVER 
[NOJSHARE 
[NO]SYSTEM 


You can override the current STEP defaults for the duration of a single 
STEP command by specifying other qualifiers. Use the SHOW STEP 
command to identify the current STEP defaults. 


If you invoke screen mode with the keypad-key sequence PF1-PF3, the 
command SET STEP NOSOURCE is entered in addition to the command 
SET MODE SCREEN. Therefore, any display of source code in output 
and DO displays that would result from a STEP command or from a 
breakpoint, tracepoint, or watchpoint being triggered is suppressed, to 
eliminate redundancy with the source display. 


Related commands: STEP, SHOW STEP. 





EXAMPLES 


DBG> SET STEP INSTRUCTION, NOSOURCE 


This command causes the debugger to execute the program to the next 
instruction when a STEP command is entered, and not to display lines of 
source code with each STEP command. 


DBG> SET STEP LINE, INTO, NOSYSTEM, NOSHARE 


This command causes the debugger to execute the program to the next 
line when a STEP command is entered, and to step into called routines in 
user space only. The debugger steps over routines in system space and in 
shareable images. 
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SET TASK 


SET TASK 


Modifies characteristics of one or more tasks or of the entire tasking system. 


Note: This command applies to Ada programs. See the VAX Ada 
documentation for complete information. 











FORMAT SET TASK [task-specf, ... |] 
PARAMETERS _task-spec 
Specifies a task value. Use any of the following forms: 
e An Ada language expression for a task vee orer example, a task 
object name. You can use a path name. 
e The task ID (for example, %TASK 2), as indicated in a SHOW TASK 
display. 
e A task built-in symbol (ZACTIVE_TASK, %CALLER_TASK, %2NEXT_ 
TASK, or %VISIBLE_TASK). 
Do not use the asterisk wildcard character (*). See the qualifier 
descriptions for details on how to specify tasks with particular qualifiers. 
QUALIFIERS /ABORT 
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Aborts the specified tasks. If no task is specified, aborts the visible task. 
The task is marked for termination but is not immediately terminated. 
The effect is identical to executing the Ada statement abort task-name, 
and causes the specified tasks to become abnormal. 


/ACTIVE | | | 
Makes the specified task the active task—the task that runs when a STEP 
or GO command is executed. Causes a task switch to the new active task 
and makes that task the visible task. The specified task must be in either 
the RUNNING or READY state. When using /ACTIVE, you must specify 
one, and only one, task. 


/ALL 


Applies the SET TASK command to all tasks. Do not specify a task nor 
the /ACTIVE, /VISIBLE, or /TIME_SLICE qualifiers with /ALL. 


/HOLD — 
/NOHOLD | 
Controls whether a specified task is put on hold. The /HOLD qualifier 


puts a specified task on hold. If no task is specified, /HOLD puts the 
visible task on hold. 


Putting a task on hold prevents a task from entering the RUNNING state. 
A task put on hold is allowed to make other state transitions; in particular, 
it can change from the SUSPENDED to the READY state. 


SET TASK 


A task that is already in the RUNNING state (the active task) can 
continue to execute as long as it remains in the RUNNING state, even 
though it is put on hold. If the task leaves the RUNNING state for any 
reason (including expiration of a time slice, if time slicing is enabled), 
it might not return to the RUNNING state until released from the hold 
condition. You can force a task into the RUNNING state with the SET 
TASK/ACTIVE command even if the task is on hold. 


The /NOHOLD qualifier releases a specified task from hold. If no task is 
specified, /‘NOHOLD releases the visible task from hold. 


/PRIORITY=n 

Sets the priority of a specified task to n, where n is a decimal integer 
from 0 to 15 inclusive. If no task is specified, sets the priority of the 
visible task to n. Note that this does not prevent the task’s priority from 
later changing in the course of execution, for example, while executing a 
rendezvous. 


/RESTORE 

Causes the priority of a specified task to be restored to the value specified 
in pragma PRIORITY. If pragma PRIORITY was not specified, the 
default value of 7 is used. If no task is specified, causes the priority of the 
visible task to be restored. 


/TIME_SLICE=t 

Sets the duration otherwise specified by pragma TIME_SLICE to the 
value t, where ¢ is a decimal integer or fixed-point value representing 
seconds. The SET TASK/TIME_SLICE=0.0 command disables time slicing. 


/VISIBLE 

Makes the specified task the visible task—the task whose call stack and 
register set are the current context for looking up names, calls, and so 
on (commands such as EXAMINE are directed at the visible task). When 
using /VISIBLE, you must specify one, and only one, task. 


Note: If no qualifier is specified, /VISIBLE is assumed by default. 





DESCRIPTION 


The possible task states are RUNNING, READY, SUSPENDED, and 


TERMINATED. 


All of the SET TASK command qualifiers except for /ALL provide a means 
of controlling the tasking environment, by directly or indirectly causing 
task state transitions. The /ALL qualifier is used to apply the SET TASK 
command to all tasks. 


Task switching can often be confusing when you are trying to debug a 
program. The SET TASK/TIME_SLICE and SET TASK/HOLD commands 
give you several ways of controlling task switching. 


Related commands: SHOW TASK, SET BREAK/EVENT, SET TRACE 
/EVENT, EXAMINE/TASK, DEPOSIT/TASK. 
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SET TASK 





EXAMPLES 


il DBG> 


2 DBG> 
DBG> 
DBG> 


DBG> 
DBG> 
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SET TASK/ACTIVE %STASK 3 
This command makes the task whose task ID is %TASK 3 the active task. 


SET TASK/HOLD/ALL 
SET TASK/ACTIVE %TASK 1 
GO 


SET TASK/ACTIVE %TASK 3 
STEP 


The SET TASK/HOLD/ALL command freezes the state of all tasks except 
the active task. The SET TASK/ACTIVE command is then used selectively 
(along with the GO command) to observe the behavior of one or more 
specified tasks in isolation. 


SET TERMINAL 


SET TERMINAL 


Sets the terminal-screen height or width that the debugger uses when it 
formats screen and other output. 











FORMAT SET TERMINAL 
You must specify at least one qualifier, either /PAGE or /WIDTH. You 
can specify both /PAGE and /WIDTH. You must specify a value for each 
qualifier used. 

QUALIFIERS /PAGE:n , 
Specifies that the terminal screen height should be set to n lines. You can — 
use any value from 18 to 100. 
/WIDTH:n 
Specifies that the terminal screen width should be set to n columns. You 
can use any value from 20 to 255. For a VT100, VT200, or VT300 series 
terminal, n is typically either 80 or 132. 

DESCRIPTION = The SET TERMINAL command enables you to define the portion of the 


screen that the debugger has available for formatting screen output. 


This command is useful with VT100-, VT200-, or VT300- series terminals, 
where you can set the screen width to typically 80 or 182 columns. It 

is also useful with workstations, where you can modify the size of the 
terminal-emulator window that the debugger uses. 


When you enter the SET TERMINAL command, all screen window ~ 
definitions (including those created by the user) are automatically adjusted 
for the new screen dimensions. For example, RH1 changes dimensions 
proportionally to remain the top right half of the screen. 


Similarly, all "dynamic" displays are automatically adjusted to maintain 
their relative dimensions. By default, all predefined and user-defined 
displays are dynamic. If you have specified /NODYNAMIC in a DISPLAY 
command, the display is no longer dynamic. In that case, the display does 
not automatically change dimensions with a SET TERMINAL command. 
However, you can always use the DISPLAY command to redisplay the 
display within any window definition (you can also use keypad-key 
combinations, such as BLUE-MINUS, to enter predefined DISPLAY 
commands). 


Related commands: SHOW TERMINAL, DISPLAY/[NOJDYNAMIC, (SET, 
SHOW, CANCEL) WINDOW, EXPAND. 
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SET TERMINAL 





EXAMPLE 


DBG> SET TERMINAL/WIDTH:132 


This command specifies that the terminal screen width be set to 132 
columns. 
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SET TRACE 


SET TRACE 


Establishes a tracepoint at the location denoted by an address expression, at 
instructions of a particular class, or at the occurrence of specified events. 








FORMAT SET TRACE [address-expressionf, ... ]] 
[WHEN (conditional-expression)] 
[DO(command]; ... ])] 
PARAMETERS address-expression 


Specifies an address expression (a program location) at which a tracepoint 
is to be set. With high-level languages, this is typically a line number, 

a routine name, or a label, and can include a path name to specify 

the entity uniquely. More generally, an address expression can also 

be a memory address or a register and can be composed of numbers 
(offsets) and symbols, as well as one or more operators, operands, or 
delimiters. Appendix D identifies the operators that can be used in 
address expressions. 


Do not specify the asterisk wildcard character (*). Do not specify 

an address expression with /ACTIVATING, /BRANCH, /CALL, 
/EXCEPTION, ANSTRUCTION[=(opcode-list)], INTO, ANOJJSB, /LINE, 
/OVER, /[NO]JSHARE, /[NO]JSYSTEM, /TERMINATING, or /VECTOR_ 
INSTRUCTION. The /MODIFY and /RETURN qualifiers are used with 
specific kinds of address expressions. 


If you specify a memory address or an address expression whose value 

is not a symbolic location, check (with the EXAMINE command) that 

an instruction actually begins at the byte of memory so indicated. If 

an instruction does not begin at this byte, a run-time error can occur 
when an instruction including that byte is executed. When you set 

a tracepoint by specifying an address expression whose value is not a 
symbolic location, the debugger does not verify that the location specified 
marks the beginning of an instruction. CALLS and CALLG routines start 
with an entry mask. 


conditional-expression 

Specifies a conditional expression in the currently set language that is to 
be evaluated whenever execution reaches the tracepoint. If the expression 
is true, trace action occurs, and the debugger reports that a tracepoint has 
been reached. If the expression is false, trace action does not occur. In this 
case, a report is not issued, the commands specified by the DO clause are 
not executed, and program execution is continued. 


command | 
Specifies a debugger command to be executed as part of the DO clause 
when trace action is taken. 
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QUALIFIERS 
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/ACTIVATING | 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). 


Causes the debugger to trace when a new process comes under debugger 
control. This is the default behavior. Do not specify an address expression 
with /ACTIVATING. See also /TERMINATING. 


/AFTER:n 


Specifies that trace action not be taken until the nth time the designated 
tracepoint is encountered (n is a decimal integer). Thereafter, the 
tracepoint occurs every time it is encountered provided that conditions 
in the WHEN clause (if specified) are true. The command SET TRACE 
/AFTER:1 has the same effect as the SET TRACE command. 


/BRANCH 


Causes the debugger to trace every branch instruction encountered during 
program execution. Do not specify an address expression with /BRANCH. 
See also /INTO and /OVER. 


/CALL 


Causes the debugger to trace every call instruction encountered during 
program execution, including the RET instruction. Do not specify an 
address expression with /CALL. See also /INTO and /OVER. 


/EVENT=event-name 


Note: This qualifier applies to Ada and SCAN programs. See the 
VAX Ada and VAX SCAN documentation for complete information. 


Causes the debugger to trace the specified event (if that event is defined 
and detected by the run-time system). If you specify an address expression 
with /EVENT, causes the debugger to trace whenever the specified event 
occurs for that address expression. Event names depend on the run-time 
facility and are identified in Appendix E for Ada and SCAN. You can 
display the event names associated with the current run-time facility by 
entering the SHOW EVENT_FACILITY command. Note that you cannot 
specify an address expression with certain event names. 


/EXCEPTION 


Causes the debugger to trace every exception that is signaled. The trace 
action occurs before any application-declared exception handlers are 
invoked. Do not specify an address expression with /EXCEPTION. 


As a result of a SET TRACE/EXCEPTION command, whenever your 
program generates an exception, the debugger reports the exception and 
resignals the exception, thus allowing any eerie ientern cs exception 
handler to execute. 


ANSTRUCTION[=(opcodef, ... ])] 


If you do not specify an opcode, causes the debugger to trace every 
instruction encountered during program execution. If you specify one 
or more opcodes, causes the debugger to trace every instruction whose 
opcode is in the list. 


SET TRACE 


Do not specify an address expression with this qualifier. If you specify a 
vector instruction, do not include an instruction qualifier (/U, /V, /M, /0, or 
/1) with the instruction mnemonic. See also INTO and /OVER. 


ANTO 

Applies only to tracepoints set with /BRANCH, /CALL, 
/INSTRUCTION[=(opcode-list)], LINE, or /VECTOR_INSTRUCTION; 
that is, when an address expression is not explicitly specified. When used 
with those qualifiers, causes the debugger to trace the specified points 
within called routines (as well as within the routine in which execution is 
currently suspended). The /INTO qualifier is the default behavior and is 
the opposite of /OVER. 


When using /INTO, you can further qualify the trace action with the 
/[NO]JSB, /INO]JSHARE, and /[NO]JSYSTEM qualifiers. 


/JSB 


/NOJSB 

Qualifies INTO. Use /[NO]JSB only with /INTO and one of the following 
qualifiers: /BRANCH, /CALL, /INSTRUCTION[=(opcode-list)], /LINE, 

or /VECTOR_INSTRUCTION. The /JSB qualifier is the default for all 
languages except DIBOL. The /JSB qualifier permits the debugger to 
set tracepoints within routines that are called by the JSB or CALL 
instruction. The /NOJSB qualifier (the DIBOL default) specifies that 
tracepoints not be set within routines called by JSB instructions. In 
DIBOL, application-declared routines are called by the CALL instruction 
and DIBOL run-time library routines are called by the JSB instruction. 
Do not specify an address expression with /[NO]JSB. 


/LINE 


Causes the debugger to trace the beginning of each source line encountered 
during program execution. Do not specify an address expression with 
/LINE. See also /INTO and /OVER. 


/MODIFY 


Causes the debugger to trace when an instruction writes to and modifies 
the value of a location indicated by a specified address expression. The 
address expression is typically a variable name. 


The command SET TRACE/MODIFY X is equivalent to the command 
SET WATCH X DO(GO). SET TRACE/MODIFY operates under the same 
restrictions as SET WATCH. 


If you specify an absolute address for the address expression, the debugger 
might not be able to associate the address with a particular data object. 
In this case, the debugger uses a default length of 4 bytes. You can change 
this length, however, by setting the type to either WORD (SET TYPE 
WORD, which changes the default length to 2 bytes) or BYTE (SET 
TYPE BYTE, which changes the default length to 1 byte). SET TYPE 
LONGWORD restores the default length of 4 bytes. 


/OVER 

Applies only to tracepoints set with /BRANCH, /CALL, 
/INSTRUCTION[=(opcode-list)], /LINE, or /VECTOR_INSTRUCTION; 
that is, when an address expression is not explicitly specified. When used 
with those qualifiers, causes the debugger to trace the specified points only 
within the routine in which execution is currently suspended (not within 
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called routines). The /OVER qualifier is the opposite of /INTO (the default 
behavior). 


/RETURN 


Causes the debugger to trace the RET (return) instruction of the routine 
associated with the specified address expression (which can be a routine 
name, line number, and so on). This qualifier can only be applied to 
routines called with a CALLS or CALLG instruction; it cannot be used 
with JSB routines. Tracing the RET instruction enables you to inspect the 
local environment (for example, obtain the values of local variables) before 
the RET instruction deletes the routine’s call frame from the call stack. 


For this qualifier, the address-expression parameter is an instruction 
address within a CALLS or CALLG routine. It can simply be a routine 
name, in which case it specifies the routine start address. However, you 
can also specify another location in a routine, so you can see only those 
returns that are taken after a certain code path is followed. 


A SET TRACE/RETURN command cancels a previous SET TRACE 
command if the same address expression is specified. 


/SHARE (default) 


/NOSHARE 

Qualifies INTO. Use (NO]SHARE only with /INTO and one of the 
following qualifiers: /BRANCH, /CALL, INSTRUCTION[=(opcode-list)], 
/LINE, or /VECTOR_INSTRUCTION. The /SHARE qualifier permits the 
debugger to set tracepoints within shareable image routines as well as 
other routines. The /NOSHARE qualifier specifies that tracepoints not be 


set within shareable images. Do not specify an address expression with 
/[NOJSHARE. 


/SILENT 
/NOSILENT (default) 


Controls whether the "trace ... " message and the source line for the 
current location are displayed at the tracepoint. The /NOSILENT qualifier 
specifies that the message is displayed. The /SILENT qualifier specifies 
that the message and source line are not displayed. The /SILENT qualifier 
overrides /SOURCE. 


/SOURCE (default) 
/NOSOURCE 


Controls whether the source line for the current location is displayed at 
the tracepoint. The /SOURCE qualifier specifies that the source line is 
displayed. The /NOSOURCE qualifier specifies that the source line is not 
displayed. The /SILENT qualifier overrides /SOURCE. See also SET STEP 
[NOJSOURCE. 


/SYSTEM (default) 


/NOSYSTEM 

Qualifies /INTO. Use /[NO]JSYSTEM only with /INTO and one of the 
following qualifiers: /BRANCH, /CALL, INSTRUCTION[=(opcode-list)], 
/LINE, or /VECTOR_INSTRUCTION. The /SYSTEM qualifier permits the 
debugger to set tracepoints within system routines (P1 space) as well as 
other routines. The /NOSYSTEM qualifier specifies that tracepoints not 


be set within system routines. Do not specify an address expression with 
/[LNO]SYSTEM. 


SET TRACE 


/TEMPORARY 


Causes the tracepoint to disappear after it is triggered (the tracepoint does 
not remain permanently set). 


/TERMINATING 


Causes the debugger to trace when a process performs an image exit. 
This is the default behavior. Note that the debugger always gains 
control and displays its prompt when the last image of a one-process 

or multiprocess program exits. Do not specify an address expression with 
/TERMINATING. See also /ACTIVATING. 


/VECTOR_INSTRUCTION 
Note: This qualifier applies to vectorized programs. 


Causes the debugger to trace every vector instruction encountered during 
program execution. Do not specify an address expression with /VECTOR_ 
INSTRUCTION. See also INTO and /OVER. 





DESCRIPTION When atracepoint is triggered, the debugger takes the following action: 
1 Suspends program execution at the tracepoint location. 


2 If/AFTER was specified when the tracepoint was set, checks the 
AFTER count. If the specified number of counts has not been reached, 
execution is resumed and the debugger does not perform the remaining 
steps. 


3 Evaluates the expression in a WHEN clause, if one was specified when 
the tracepoint was set. If the value of the expression is false, execution 
is resumed and the debugger does not perform the remaining steps. 


4 Reports that execution has reached the tracepoint location by issuing a 
"trace ... " message, unless /SILENT was specified. 


5 Displays the line of source code corresponding to the tracepoint, unless 
/NOSOURCE or /SILENT was specified when the breakpoint was set, 
or SET STEP NOSOURCE was entered previously. 


6 Executes the commands in a DO clause, if one was specified when the 
tracepoint was set. 


7 Resumes execution. 


You set a tracepoint at a particular location in your program by specifying 
an address expression with the SET TRACE command. You set a 
tracepoint on consecutive source lines, classes of instructions, or events 
by specifying a qualifier with the SET TRACE command. Generally, you 
must specify either an address expression or a qualifier, but not both. 
The only exception is with the /EVENT qualifier, which requires that you 
specify an event name keyword and permits you also to specify an address 
expression for certain event names. 


The /LINE qualifier sets a tracepoint on each line of source code. 
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The following qualifiers set tracepoints on classes of instructions. Note 
that use of these qualifiers and of the /LINE qualifier causes the debugger 
to trace every instruction of your program as it executes and thus 
significantly slows down execution: 


/BRANCH 

/CALL 
/AINSTRUCTION[=(opcode[, ... ])] 
/RETURN 
/VECTOR_INSTRUCTION 


The following qualifiers set tracepoints on classes of events: 


/ACTIVATING 
/EVENT=event-name 
/EXCEPTION 
/TERMINATING 


The following qualifiers affect what happens at a routine call: 


INTO 
/[NO|JSB 
/OVER 
/[NOJSHARE 
/[NOJSYSTEM 


The following qualifiers affect what output is displayed when a tracepoint 
is reached: 


/[NOJSILENT 
/[NO|SOURCE 


The following qualifiers affect the timing and duration of tracepoints: 


/AFTER:n 
[TEMPORARY 


The /MODIFY qualifier is used to monitor changes at program locations 
(typically changes in the values of variables). 


If you set a tracepoint at a location currently used as a breakpoint, the 
breakpoint is canceled in favor of the tracepoint, and vice versa. 


Tracepoints can be user defined or predefined. User defined tracepoints are 
those that you set explicitly with the SET TRACE command. Predefined 
tracepoints, which depend on the type of program you are debugging 

(for example, Ada or multiprocess), are established automatically when 
you invoke the debugger. Use the SHOW TRACE command to identify 

all tracepoints that are currently set. Any predefined tracepoints are 
identified as such. 


User defined and predefined tracepoints are set and canceled 
independently. For example, a location or event can have both a user 
defined and a predefined tracepoint. Canceling the user defined tracepoint 
does not affect the predefined tracepoint, and conversely. 


SET TRACE 


Related commands: (SHOW, CANCEL) TRACE, CANCEL ALL, SET 
BREAK, SET WATCH, GO, (SET, SHOW) EVENT_FACILITY, SET STEP 
[LNO]JSOURCE. 





EXAMPLES 


DBG> SET TRACE SUB3 


This command causes the debugger to trace the beginning of routine SUB3 
when that routine is executed. 


DBG> SET TRACE/BRANCH/CALL 


This command causes the debugger to trace every BRANCH instruction 
and every CALL instruction encountered during program execution. 


DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM 


This command causes the debugger to trace the beginning of every source 
line, including lines in called routines (INTO) but not in shareable image 
routines (/NOSHARE) or system routines (/(NOSYSTEM). 


DBG> SET TRACE/NOSOURCE TEST5\SLINE 14 WHEN (X .NE. 2) DO (EXAMINE Y) 


This command causes the debugger to trace line 14 of module TEST5 
when X is not equal to 2. At the tracepoint, the command EXAMINE Y is 
issued. The /NOSOURCE qualifier suppresses the display of source code 
at the tracepoint. 


DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0) 


This command causes the debugger to trace when X is not equal to 0. The 
condition is tested at each instruction encountered during execution. 


6 DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K) 


This SET TRACE command causes the debugger to trace the beginning 
of routine SUB2 during execution. At the tracepoint, the DO clause sets 

a watchpoint on variable K. The /SILENT qualifier on the SET TRACE 
command suppresses the "trace ... " message and the display of source 
code at the tracepoint. This example shows a convenient way of setting a 
watchpoint on a nonstatic (stack or register) variable. A nonstatic variable 
is defined only when its defining routine (SUB2, in this case) is active (on 
the call stack). 


DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X) 


This SET TRACE command causes the debugger to trace the RET 
instruction of routine ROUT4 (that is, just before execution returns to 

the calling routine). At the tracepoint, the DO clause issues the command 
EXAMINE X. This example shows a convenient way of obtaining the value 
of a nonstatic variable just before execution leaves that variable’s defining 
routine. 
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3) DBG> SET TRACE/EVENT=TERMINATED 


This command causes the debugger to trace the point at which an Ada 
task makes a transition to the TERMINATED state. 
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SET TYPE 


Establishes the default type to be associated with program locations that do 
not have a symbolic name (and, therefore, do not have an associated compiler 
generated type). When used with /OVERRIDE, establishes the default type to 
be associated with all locations, overriding any compiler generated types. 





FORMAT SETTYPE type-keyword 





PARAMETERS _ type-keyword 
Specifies the default type to be established. Valid keywords are as follows: 


ASCIC Sets the default type to counted ASCII string with a 1-byte 
count field that precedes the string and gives its length. 
AC is also accepted as a keyword. 


ASCID Sets the default type to ASCII string descriptor. The 
CLASS and DTYPE fields of the descriptor are not 
checked, but the LENGTH and POINTER fields provide 
the character length and address of the ASCII string. 
The string is then displayed. AD is also accepted as a 
keyword. 


ASClkn Sets the default type to ASCII character string (length n 
bytes). The length indicates both the number of bytes 
of memory to be examined and the number of ASCII 
characters to be displayed. If you do not specify a value 
for n, the debugger uses the default value of 4 bytes. The 
value n is interpreted in decimal radix. 

ASCIW Sets the default type to counted ASCII string with a 2-byte 
count field that precedes the string and gives its length. 
This data type occurs in PASCAL and PL/I. AW is also 
accepted as a keyword. 


ASCIZ Sets the default type to zero-terminated ASCII string. The 
ending zero byte indicates the end of the string. AZ is also 
accepted as a keyword. 

BYTE Sets the default type to byte integer (length 1 byte). 


D_FLOAT Sets the default type to D_floating (length 8 bytes). Values 
of type D_floating can range from .29 « 10~*8 to 1.7 « 10% 
with approximately 16 decimal digits precision. 


DATE_TIME Sets the default type to date and time. This is a quadword 
integer (length 8 bytes) containing the internal VMS 
representation of date and time. Values are displayed 
in the format dd-mmm-yyyy hh:mm:ss.xx. Specify an 
absolute date and time as follows: 


[dd-mmm-yyyy[:]] [hh:mm:ss.cc] 
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FLOAT Seis the default type to F_floating (length 4 bytes). Values 
of type F_floating can range from .29 « 107 to 1.7 « 10% 
with approximately 7 decimal digits precision. 


G_FLOAT Sets the default type to G_floating (length 8 bytes). Values 
of type G_floating can range from .56 + 1078 to .9 « 10% 
with approximately 15 decimal digits precision. 


H_FLOAT Sets the default type to H_floating (length 16 bytes). 
Values of type H_floating can range from .84 « 107° to 
59 « 109°? with approximately 33 decimal digits precision. 

INSTRUCTION Sets the default type to VAX instruction (variable length, 


depending on the number of instruction operands and the 
kind of addressing modes used). 


LONGWORD Sets the default type to longword integer (length 4 bytes). 
This is the default type for program locations that do not 
have a symbolic name (do not have a compiler generated 


type). 
OCTAWORD Sets the default type to octaword integer (length 16 bytes). 
PACKED:n Sets the default type to packed decimal. The value of n 


is the number of decimal digits. Each digit occupies one 
nibble (4 bits). 


QUADWORD Sets the default type to quadword integer (length 8 bytes). 


TYPE=(expression) Sets the default type to the type denoted by expression 
(the name of a variable or data type declared in the 
program). This enables you to specify an application- 
declared type. 


WORD Sets the default type to word integer (length 2 bytes). 





QUALIFIERS 


/OVERRIDE 


Associates the type specified with all program locations, whether or not 
they have a symbolic name (whether or not they have an associated 
compiler generated type). 





DESCRIPTION 
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When you use the EXAMINE, DEPOSIT, or EVALUATE commands, 
the default types associated with address expressions influence how the 
debugger interprets and displays program entities. 


The debugger recognizes the compiler generated types associated with 
symbolic address expressions (symbolic names declared in your program), 
and it interprets and displays the contents of these locations accordingly. 
For program locations that do not have a symbolic name and, therefore, 
no associated compiler generated type, the default type in all languages is 
longword integer. 


The SET TYPE command enables you to change the default type 
associated with locations that do not have a symbolic name. The SET 
TYPE/OVERRIDE command enables you to set a default type for all 
program locations, both those that do and do not have a symbolic name. 


SET TYPE 


The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII, 
/BYTE, /G_FLOAT, and so on) that enable you to override, for the duration 
of a single command, the type previously associated with any program 
location. 


Related commands: SHOW TYPE, CANCEL TYPE/OVERRIDE, (SET, 
SHOW, CANCEL) RADIX, (SET, SHOW, CANCEL) MODE, EXAMINE, 
DEPOSIT. 





EXAMPLES 


DBG> SET TYPE ASCII:8 


This command establishes an 8-byte ASCII character string as the default 
type associated with untyped program locations. 


DBG> SET TYPE/OVERRIDE LONGWORD 


This command establishes longword integer as the default type associated 
with both untyped program locations and program locations that have 
compiler generated types. 


DBG> “SEY “TYEE. D2 BLOAT 


This command establishes D_Floating as the default type associated with 
untyped program locations. 


DBG> SET TYPE TYPE=(S ARRAY) 


This command establishes the type of the variable S_ARRAY as the default 
type associated with untyped program locations. 
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SET VECTOR MODE 


Note: This command applies to vectorized programs. 


Enables or disables a debugger vector mode option. 





FORMAT 


SET VECTOR_MODE _vecitor-mode-option 





PARAMETERS 


vector-mode-option 
Specifies the vector mode option. Valid keywords are as follows: 


SYNCHRONIZED 


NOSYNCHRONIZED 


Specifies that the debugger force automatic synchronization 
between the scalar and vector processors whenever a vector 
instruction is executed. Specifically, the debugger issues 

a SYNC instruction after every vector instruction and, in 
addition, an MSYNC instruction after any vector instruction 
that accesses memory. This forces the completion of all 
activities associated with the vector instruction that is being 
synchronized: 


_¢ — Any exception that was caused by a vector instruction is 


delivered before the next scalar instruction is executed. 
Note that forcing the delivery of a pending exception 
triggers an exception breakpoint or tracepoint (if one was 
set) or invokes an exception handier (if one is available at 
that location in the program). 


« Any read or write operation between vector registers and 
either the general registers or memory is completed before 
the next scalar instruction is executed. 


Note that the command SET VECTOR_MODE 
SYNCHRONIZED does not issue an immediate SYNC or 
MSYNC instruction at the time it is issued. Use the command 
SYNCHRONIZE VECTOR_MODE to force immediate 
synchronization. 


Specifies that the debugger not force synchronization between 
the scalar and vector processors except for internal debugger 
purposes. As a result, any synchronization is controlled entirely 
by the program, and the program runs as if it were not under 
debugger control. NOSYNCHRONIZED is the default vector 
mode. 





DESCRIPTION 
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Vector mode options control the way in which the debugger interacts with 
the vector processor. See the parameter descriptions for details about the 


SET VECTOR_MODE command. 


Related commands: SHOW VECTOR_MODE, SYNCHRONIZE VECTOR_ 
MODE. 


SET VECTOR MODE 





EXAMPLES 


DBG> SET VECTOR MODE SYNCHRONIZED 


This command causes the debugger to force synchronization between the 
scalar and vector processors after each vector instruction is executed. 


DBG> SHOW VECTOR MODE 
Vector mode is nonsynchronized 
DBG> SET VECTOR MODE SYNCHRONIZED @ 
DBG> SHOW VECTOR MODE 
Vector mode is synchronized 
DBG> STEP @ 
stepped to .MAIN.\SUB\%LINE 99 
99: VVDIVD vi,V0,V2 
DBG> STEP © 
SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%SLINE 100 
100: CLRL RO 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ The command SET VECTOR_MODE SYNCHRONIZED causes the 
debugger to force automatic synchronization between the scalar and 
vector processors whenever a vector instruction is executed. 


@ This STEP command suspends program execution on line 99, just 
before a VVDIVD instruction is executed. Assume that, in this 
example, the instruction will trigger a floating-point divide-by-zero 
exception. 


© This STEP command executes the VVDIVD instruction, which triggers 
the exception. Note that the vector exception is delivered immediately 
because the debugger is being operated in synchronized vector mode. 
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SET WATCH 


Establishes a watchpoint at the location denoted by an address expression. 





FORMAT SET WATCH address-expression[,... ] 
[WHEN (conditional-expression)] 
[DO(command]; ... ])] 





PARAMETERS address-expression 
Specifies an address expression (a program location) at which a watchpoint 
is to be set. With high-level languages, this is typically the name of a 
program variable and can include a path name to specify the variable 
uniquely. More generally, an address expression can also be a memory 
address or a register and can be composed of numbers (offsets) and 
symbols, as well as one or more operators, operands, or delimiters. 
Appendix D identifies the operators that can be used in address 
expressions. 


Do not specify the asterisk wildcard character (* ). 


See Chapter 11 for information that is specific to vector registers. 


conditional-expression 

Specifies a conditional expression in the currently set language that is to 
be evaluated whenever execution reaches the watchpoint. If the expression 
is true, watch action occurs, and the debugger reports that a watchpoint 
has been triggered. If the expression is false, watch action does not occur. 
In this case, a report is not issued, the commands specified by the DO 
clause are not executed, and program execution is continued. 


command 


Specifies a debugger command to be executed as part of the DO clause 
when watch action is taken. 





QUALIFIERS /AFTER:n 


Specifies that watch action not be taken until the nth time the designated 
watchpoint is encountered (n is a decimal integer). Thereafter, the 
watchpoint occurs every time it is encountered provided that conditions in 
the WHEN clause are true. The command SET WATCH/AFTER:1 has the 
same effect as the SET WATCH command. 


/JAINTO 


Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions not only within the defining routine, but also within a routine 
that is called from the defining routine (and any other such nested calls). 
SET WATCHANTO enables you to monitor nonstatic variables within 
called routines more precisely than SET WATCH/OVER; but the speed of 
execution within called routines is faster with SET WATCH/OVER. 
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/OVER 


Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions only within the defining routine, not within a routine that 

is called by the defining routine. As a result, the debugger executes a 
called routine at normal speed and resumes tracing instructions only when 
execution returns to the defining routine. SET WATCH/OVER provides 
faster execution than SET WATCH/INTO; but if a called routine modifies 
the watched variable, execution is interrupted only upon returning to the 
defining routine. SET WATCH/OVER is the default behavior when you set 
watchpoints on nonstatic variables. 


/SILENT 
/NOSILENT (default) 


Controls whether the "watch ... " message and the source line for 

the current location are displayed at the watchpoint. The /NOSILENT 
qualifier specifies that the message is displayed. The /SILENT qualifier 
specifies that the message and source line are not displayed. The /SILENT 
qualifier overrides /SOURCE. 


/SOURCE (default) 
/NOSOURCE 


Controls whether the source line for the current location is displayed at 
the watchpoint. The /SOURCE qualifier specifies that the source line is 
displayed. The /NOSOURCE qualifier specifies that the source line is not 
displayed. The /SILENT qualifier overrides /SOURCE. See also SET STEP 
[NO]JSOURCE. 


/STATIC 
/NOSTATIC 


Enables you to override the debugger’s default determination of whether 
a specified variable (watchpoint location) is static or nonstatic. The 
/STATIC qualifier specifies that the debugger should treat the variable 
as a static variable, even though it might be allocated in Pl space. 

This causes the debugger to monitor the location by using the faster 
write-protection method rather than by tracing every instruction. The 
/NOSTATIC qualifier specifies that the debugger should treat the variable 
as a nonstatic variable, even though it might be allocated in PO space. 
The /NOSTATIC qualifier causes the debugger to monitor the location by 
tracing every instruction. Exercise caution when using these qualifiers. 


/TEMPORARY 


Causes the watchpoint to disappear after it is triggered (the watchpoint 
does not remain permanently set). 





DESCRIPTION When an instruction causes the modification of a watchpoint location, the 
debugger takes the following action: 


1 Suspends program execution after that instruction has completed 
execution. 


2 If /AFTER was specified when the watchpoint was set, checks the 
AFTER count. If the specified number of counts has not been reached, 
execution continues and the debugger does not perform the remaining 
steps. 
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3 Evaluates the expression in a WHEN clause, if one was specified 
when the watchpoint was set. If the value of the expression is false, 
execution continues and the debugger does not perform the remaining 
steps. 


4 Reports that execution has reached the watchpoint location, unless 
/SILENT was specified ("watch of... "). 


Reports the old (unmodified) value at the watchpoint location. 
Reports the new (modified) value at the watchpoint location. 


Displays the line of source code at which execution is suspended, 
unless /NOSOURCE or /SILENT was specified when the watchpoint 
was set, or SET STEP NOSOURCE was entered previously. 


8 Executes the commands in a DO clause, if one was specified when 
the watchpoint was set. If the DO clause contains a GO command, 
execution continues and the debugger does not perform the next step. 


9 Issues the prompt. 


For high-level language programs, the address expressions you specify 
with the SET WATCH command are typically variable names. If you 
specify an absolute memory address that is associated with a compiler- 
generated type, the debugger symbolizes the address and uses the length 
in bytes associated with that type to determine the length in bytes of the 
watchpoint location. If you specify an absolute memory address that the 
debugger cannot associate with a compiler-generated type, the debugger 
watches 4 bytes of memory, by default, beginning at the byte identified by 
the address expression. You can change this length, however, by setting 
the type to either WORD (SET TYPE WORD, which changes the default 
length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default 
length to 1 byte). SET TYPE LONGWORD restores the default length of 4 


bytes. 


You can set watchpoints on aggregates (that is, entire arrays or records). 
A watchpoint set on an array or record triggers if any element of the array 
or record changes. Thus, you do not need to set watchpoints on individual 
array elements or record components. Note, however, that you cannot set 
an aggregate watchpoint on a variant record. 


You can also set a watchpoint on a record component, on an individual 
array element, or on an array slice (a range of array elements). A 
watchpoint set on an array slice triggers if any element within that slice 
changes. When setting the watchpoint, use the syntax of the current 
language. 


See Chapter 11 for information that is specific to vector registers. 


The following qualifiers affect what output is seen when a watchpoint is 
reached: 


/[NOJSILENT 
/[[NOJSOURCE 


SET WATCH 


The following qualifiers affect the timing and duration of watchpoints: 


/AFTER:n 
/TEMPORARY 


The following qualifiers apply only to nonstatic variables: 


INTO 
/OVER 


The following qualifiers are used to override the debugger’s determination 
of whether a variable is static or nonstatic: 


/[LNO]STATIC 


Static and Nonstatic Watchpoints 


The technique for setting a watchpoint depends on whether the variable is 
static or nonstatic. A static variable is associated with the same memory 
address throughout execution of the program. You can always set a 
watchpoint on a static variable throughout execution. 


A nonstatic variable is allocated on the call stack or in a register and has a 
value only when its defining routine is active (on the call stack). Therefore, 
you can set a watchpoint on a nonstatic variable only when execution is 
currently suspended within the scope of the defining routine (including 
any routine called by the definining routine). The watchpoint is canceled 
when execution returns from the defining routine. 


Another distinction between static and nonstatic watchpoints is speed 
of execution. To watch a static variable, the debugger write-protects the 
page containing the variable. If your program attempts to write to that 
page, an access violation occurs and the debugger handles the exception, 
determining whether the watched variable was modified. Except when 
writing to that page, the program executes at normal speed. 


To watch a nonstatic variable, the debugger traces every instruction 

in the variable’s defining routine and checks the value of the variable 
after each instruction has been executed. Since this significantly slows 
down execution, the debugger issues a message when you set a nonstatic 
watchpoint. 


As explained in the next paragraphs, the /[NOJSTATIC and /INTO and 
/OVER qualifiers enable you to exercise some control over speed of 
execution and other factors when watching variables. 


The debugger determines whether a variable is static or nonstatic by 
checking how it is allocated. Typically, a static variable is in PO space (0 to 
3FFFFFFF, hexadecimal); a nonstatic variable is in P1 space (40000000 to 
7FFFFFFF) or in a register. The debugger issues a warning if you try to 
set a watchpoint on a variable that is allocated in Pl space or in a register 
when execution is not currently suspended within the scope of the defining 
routine. 


The /[NOJSTATIC qualifiers enable you to override this default behavior. 
For example, if you have allocated nonstack storage in P1 space, use 
the /STATIC qualifier when setting a watchpoint on a variable that is 
allocated in that storage area. This enables the debugger to use the 
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faster write-protection method of watching the location instead of tracing 
every instruction. Conversely, if, for example, you have allocated your 
own call stack in PO space, use the /NOSTATIC qualifier when setting a 
watchpoint on a variable that is allocated on that call stack. This enables 
the debugger to treat the watchpoint as a nonstatic watchpoint. 


You can also control the execution speed for nonstatic watchpoints in called 
routines by means of the /INTO and /OVER qualifiers. 


Global Section Watchpoints 


You can set watchpoints on variables or arbitrary program locations in 
global sections. A global section is a region of memory that is shared 
among all processes of a multiprocess program. A watchpoint that is set 
on a location in a global section (a global section watchpoint) triggers when 
any process modifies the contents of that location. 


You set a global section watchpoint just as you would set a watchpoint on a 
static variable. However, because of the way the debugger monitors global 
section watchpoints, note the following point. When setting watchpoints 
on arrays or records, performance is improved if you specify individual 
elements rather than the entire structure with the SET WATCH command. 


If you set a watchpoint on a location that is not yet mapped to a global 
section, the watchpoint is treated as a conventional static watchpoint. 
When the location is subsequently mapped to a global section, the 
watchpoint is automatically treated as a global section watchpoint and 
an informational message is issued. The watchpoint is then visible from 
each process of the multiprocess program. 


Related commands: (SHOW, CANCEL) WATCH, SET BREAK, SET 
TRACE, SET STEP [NO]SOURCE. 





EXAMPLES 


DBG> SET WATCH MAXCOUNT 


This command establishes a watchpoint on the variable MAXCOUNT. 


DBG> SET WATCH ARR 


DBG> GO 


watch of SUBR\ARR at SUBR\SLINE 12+8 


old value: 


(1): 
(2) 2 
(3): 
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7 
12 
3 


SET WATCH 


new value: 


(1): 7 
(2): 12 
(3): 28 


break at SUBR\SLINE 14 
DBG> 


In this example, the SET WATCH command sets a watchpoint on the 
three-element integer array, ARR. Execution is then resumed with the GO 
command. The watchpoint triggers whenever any array element changes. 
In this case the third element changed. 


DBG> SET WATCH ARR(3) 


In this example, the SET WATCH command sets a watchpoint on element 
3 of array ARR (FORTRAN array syntax). The watchpoint triggers 
whenever element 3 changes. 


DBG> SET WATCH P_ARR[3:5] 


In this example, the SET WATCH command sets a watchpoint on the array 
slice consisting of elements 3 to 5 of array P_ARR (Pascal array syntax). 
The watchpoint triggers whenever any of these elements change. 


DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K) 


In this example, variable K is a nonstatic variable and is defined only 
when its defining routine, SUB2, is active (on the call stack). The SET 
TRACE command sets a tracepoint on SUB2. When the tracepoint is 
triggered during execution, the DO clause sets a watchpoint on K. The 
watchpoint is then canceled when execution returns from routine SUB2. 
The /SILENT qualifier on the SET TRACE command suppresses the 
"trace ... " message and the display of source code at the tracepoint. 


DBG 1> SET WATCH ARR(1) 
DBG_1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 
DBG 1> GO 
S$DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has been remapped 
to a global section 
predefined trace on activation at routine PPL3 in %PROCESS NUMBER 2 
predefined trace on activation at routine PPL3 in %PROCESS NUMBER 3 
watch of PPL3\ARR(1) at PPL3\%LINE 93 in SPROCESS NUMBER 2 
93: ARR(1) = INDEX 
Old value: 0 
new value: 1 
break at PPL3\SLINE 94 in %PROCESS NUMBER 2 
94; ARR(I) = I 
DBG 2> DO (SHOW WATCH) 
For %PROCESS NUMBER 1 
watchpoint of PPL3\ARR(1) [global-section watchpoint ] 
For %PROCESS NUMBER 2 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For %PROCESS NUMBER 3 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
DBG 2> 
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In this example of a global section watchpoint, the SET WATCH command 
sets a watchpoint on element 1 of array ARR. Because ARR has not yet 
been mapped to a global section, the SHOW WATCH command identifies 
the watchpoint as a conventional static watchpoint. 


After the GO command resumes execution, ARR is remapped to a global 
section. The watchpoint is automatically treated as a global section 
watchpoint. 


Processes 2 and 3 come under debugger control, then the watchpoint is 
triggered in process 2, interrupting execution. At this point, the SHOW 
WATCH command confirms that the watchpoint is visible from each 
process. 
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SET WINDOW 


Creates a screen window definition. 





FORMAT 


SET WINDOW wname AT (siart-line, line-count 
[,start-col,col-count]) 





PARAMETERS 


wname 
Specifies the name of the window you are defining. If a window definition 
with that name already exists, it is canceled in favor of the new definition. 


start-line 
Specifies the starting line number of the window. This line displays the 
window title, or header line. The top line of the screen is line 1. 


line-count 

Specifies the number of text lines in the window, not counting the header 
line. Line-count must be at least 1. The sum of start-line and line-count 
must not exceed the current screen height. 


start-col 

Specifies the starting column number of the window. This is the column at 
which the first character of the window is displayed. The leftmost column 
of the screen is column 1. 


col-count 

Specifies the number of characters per line in the window. Col-count must 
be at least 1. The sum of start-col and col-count must not exceed the 
current screen width. 





DESCRIPTION 


A screen window is a rectangular region on the terminal screen through 
which you can view a display. The SET WINDOW command establishes a 
window definition by associating a window name with a screen region. You 
specify the screen region in terms of a starting line and height (line count) 
and, optionally, a starting column and width (column count). If you do not 
specify the starting column and column count, they default to column 1 
and the current screen width. 


You can specify a window region in terms of expressions that use the 
built-in symbols %PAGE and %WIDTH. 


You can use the names of any windows you have defined with the SET 
WINDOW command in a DISPLAY command to position displays on the 
screen. 


Window definitions are dynamic—that is, window dimensions expand and 
contract proportionally when a SET TERMINAL command changes the 
screen width or height. 
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SET WINDOW 


Related commands: (SHOW, CANCEL) WINDOW, (SET SHOW, CANCEL) 
DISPLAY, DISPLAY, (SET, SHOW) TERMINAL. 





EXAMPLES 


DBG> SET WINDOW ONELINE AT (1,1) 


This command defines a window named ONELINE at the top of the screen. 
The window is one line deep and, by default, spans the width of the screen. 


DBG> SET WINDOW MIDDLE AT (9,4,30,20) 


This command defines a window named MIDDLE at the middle of the 
screen. The window is 4 lines deep starting at line 9, and 20 columns wide 
starting at column 30. 


DBG> SET WINDOW FLEX AT (%SPAGE/4, %PAGE/2, SWIDTH/4, SWIDTH/2) 


This command defines a window named FLEX that occupies a region 
around the middle of the screen and is defined in terms of the current 
screen height (%PAGE) and width (7% WIDTH). 
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SHOW ABORT_KEY 


SHOW ABORT_KEY 


Identifies the CTRL—key sequence currently defined to abort the execution of 
a debugger command or to interrupt program execution. 





FORMAT SHOW ABORT_KEY 





DESCRIPTION _ By default, the CTRL/C sequence, when entered within a debugging 
session, aborts the execution of a debugger command and interrupts 
program execution. The SET ABORT_KEY command enables you to 
assign the abort function to another CTRL—key sequence. The SHOW 
ABORT_KEY command identifies the CTRL—key sequence currently in 
effect for the abort function. 


Related commands: CTRL/C, SET ABORT_KEY. 





EXAMPLE 


DBG> SHOW ABORT KEY 

Abort Command Key is CTRL C 
DBG> SET ABORT KEY = CTRL P 
DBG> SHOW ABORT KEY 

Abort Command Key is CTRL P 
DBG> 


The firsts SHOW ABORT_KEY command identifies the default abort 
command key sequence, CTRL/C. The command SET ABORT_KEY = 
CTRL_P assigns the abort-command function to the CTRL/P sequence, as 
verified by the second SHOW ABORT_KEY command. 
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SHOW AST 


SHOW AST 


Indicates whether delivery of ASTs is enabled or disabled. 





FORMAT SHOW AST. 





DESCRIPTION The SHOW AST command indicates whether delivery of ASTs is enabled 
or disabled. Note that the command does not identify an AST whose 
delivery is pending. The delivery of ASTs is enabled by default and with 
the ENABLE AST command. The delivery of ASTs is disabled with the 
DISABLE AST command. 


Related commands: (ENABLE, DISABLE) AST. 





EXAMPLE 
DBG> 2Sow AST 
ASTs are enabled 
DBG> Pr SABiUuE AST 
DBG> sow AST 
ASTs are disabled 
DBG> 


The SHOW AST command indicates whether the delivery of ASTs is 
enabled. 
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SHOW ATSIGN 


SHOW ATSIGN 


Identifies the default file specification established with the last SET ATSIGN 
command. The debugger uses this file specification when processing the 
@file-spec command. 





FORMAT SHOW ATSIGN 





DESCRIPTION _ Related commands: SET ATSIGN, @file-spec. 





EXAMPLES 


DBG> SHOW ATSIGN 
No indirect command file default in effect, using DEBUG.COM 
DBG> 


This example shows that, if the SET ATSIGN command was not used, 
command procedures are assumed to have the default file specification 
SYS$DISK:[ JDEBUG.COM. 


NO | 


DBG> SET ATSIGN USER: [JONES.DEBUG].DBG 

DBG> SHOW ATSIGN 

Indirect command file default is USER: [JONES.DEBUG] .DBG 
DBG> 


In this example, the SHOW ATSIGN command indicates the default file 
specification for command procedures, as previously established with the 
SET ATSIGN command. 
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SHOW BREAK 


SHOW BREAK 


Displays information about breakpoints. 





FORMAT 


SHOW BREAK 





QUALIFIERS 


/PREDEFINED 


Displays information about predefined breakpoints. 


/USER 


Displays information about user defined breakpoints. 





DESCRIPTION 


The SHOW BREAK command displays information about breakpoints that 
are currently set, including any options such as WHEN or DO clauses, 
/AFTER counts, and so on. 


By default, SHOW BREAK displays information about both user defined 
and predefined breakpoints Gf any). This is equivalent to entering the 
command SHOW BREAK/USER/PREDEFINED. User defined breakpoints 
are set with the SET BREAK command. Predefined breakpoints are set 
automatically when you invoke the debugger, and they depend on the type 
of program you are debugging. 


See Section 9.3.2 for information about predefined breakpoints that are 
associated with Ada tasking exception events. 


If you established a breakpoint using the /AFTER:n command qualifier 
with the SET BREAK command, the SHOW BREAK command displays 
the current value of the decimal integer n, that is, the originally specified 
integer value minus one for each time the breakpoint location was reached. 
(The debugger decrements n each time the breakpoint location is reached 
until the value of n is zero, at which time the debugger takes break action.) 


Related commands: (SET, CANCEL) BREAK. 





EXAMPLES 


DBG> SHOW BREAK 


breakpoint at SUB1\LOOP 
breakpoint at MAIN\MAIN+1F 

do (EX SUB1\D ; EX/SYMBOLIC PSL; GO) 
breakpoint at routine SUB2\SUB2 


/after: 2 
DBG> 
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The SHOW BREAK command identifies all breakpoints that are 
currently set. This example indicates user defined breakpoints that are 
triggered whenever execution reaches SUB1\ LOOP, MAIN\ MAIN, and 
SUB2\ SUB2, respectively. 


SHOW BREAK 


DBG> SHOW BREAK/PREDEFINED 

predefined breakpoint on Ada event "DEPENDENTS EXCEPTION" 
for any value 

predefined breakpoint on Ada event "EXCEPTION TERMINATED" 
for any value 

DBG> 


This command identifies the predefined breakpoints that are currently set. 
The example shows two predefined breakpoints, which are associated with 
Ada tasking exception events. These breakpoints are set automatically by 
the debugger for all Ada programs and for any mixed language program 
that is linked with an Ada module. 
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SHOW CALLS 


SHOW CALLS 


Identifies the currently active routine calls (the call stack). 





FORMAT 


SHOW CALLS [nj 





PARAMETERS " 


A decimal integer that specifies the number of call frames to be identified. 
By default, all currently active call frames are identified. 





DESCRIPTION 


CD-214 


Whenever a call is made to a routine as your program executes, the VMS 

operating system creates a separate call frame on the call stack. Each call 
frame stores information about the calling routine. The call frame for the 

most recently called routine is on the top of the call stack. 


When a routine returns execution to its caller, the call frame for that 
routine is removed from the call stack. 


The SHOW CALLS command shows a traceback that lists the sequence of 
active routine calls that lead to the routine in which execution is currently 
suspended. Any recursive routine calls are shown in the display, so you 
can use the SHOW CALLS command to examine the chain of recursion. 


One line of information is displayed for each call frame, starting with the 
most recent call. The top line identifies the currently executing routine, 
the next line identifies its caller, the following line identifies the caller of 
the caller, and so on. 


The following information is provided for each call frame: 


e The name of the enclosing module. An asterisk (*) to the left of a 
module name indicates that the module is set. 


e The name of the calling routine, provided the module is set (the first 
line shows the currently executing routine). 


e The line number where the call was made in that routine, provided the 
module is set (the first line shows the line number at which execution 
is suspended). 


e The value of the PC in the calling routine at the time that control was 
transferred to the called routine. The PC value is shown as a memory 
address relative to the address of the name of the routine and also as 
an absolute address. 


Note that, even if your program contains no routine calls, the SHOW 
CALLS command displays an active call. The reason for this is that your 
program has a stack frame built for it when it is first activated. Thus, if 
the SHOW CALLS display shows no active calls, either your program has 
terminated or the call stack has been corrupted. 


Related commands: SHOW STACK, SHOW SCOPE. 


SHOW CALLS 





DBG> SHOW CALLS 

module name routine name line rel PC abs PC 
SUB2 SUB2 00000002 O0O00085A 
*SUB1 SUB1 5 00000014 00000854 
*xXMAIN MAIN 10 0000002C 0000082C 
DBG> 


This command displays information about the sequence of currently active 
procedure calls. 
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SHOW DEFINE 


SHOW DEFINE 


Identifies the default qualifier (/(ADDRESS, /COMMAND, /PROCESS_GROUP, 
or /VALUE) currently in effect for the DEFINE command. 





FORMAT SHOW DEFINE 





DESCRIPTION The default qualifier for the DEFINE command is the default qualifier 
last established with the SET DEFINE command. If no SET DEFINE 
command was entered, the default qualifier is /ADDRESS. 


To identify a symbol defined with the DEFINE command, use the SHOW 
SYMBOL/DEFINED command. 


Related commands: SET DEFINE, DEFINE, DEFINE/PROCESS_GROUP, 
DELETE, SHOW SYMBOL/DEFINED. 





EXAMPLE 


DBG> SHOW DEFINE 


Current setting is: DEFINE/ADDRESS 
DBG> 


The SHOW DEFINE command indicates that the DEFINE command is set 
for definition by address. 
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SHOW DISPLAY 


SHOW DISPLAY 


Identifies one or more existing screen displays. 





FORMAT 


SHOW DISPLAY [disp-namef, ... ]] 





PARAMETERS 


disp-name 

Specifies the name of a display. If you do not specify a name, or if you 
specify the asterisk wildcard character (*) by itself, all display definitions 
are listed. You can use * within a display name. Do not specify a display 
name with /ALL. 





QUALIFIERS 


/ALL 


Lists all display definitions. Do not specify a display name with /ALL. 


/SUFFIX[=process-identifier-type] 

Note: This qualifier applies to a multiprocess debugging 
configuration (when DBG$PROCESS has the value 
MULTIPROCESS). Use this qualifier only directly after a display 
name. 


Appends a process-identifying suffix to a display name. The suffix denotes 
the visible process at the time the command was issued. This qualifier is 
used primarily in command procedures when specifying display definitions 
or key definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS NUMBER _ The display-name suffix is the process number (as shown in 
a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process identification 
number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the 
process identifier type used for the display-name suffix is, by default, the 
same as that used for the prompt suffix (see SET PROMPT/SUFFIX). 





DESCRIPTION 


The SHOW DISPLAY command lists all displays according to their order 
in the display list. The most hidden display is listed first, and the display 
that is on top of the display pasteboard is listed last. 


For each display, the SHOW DISPLAY command lists its name, maximum 
size, screen window, and display kind (including any debug command list). 
It also identifies whether the display is removed from the pasteboard or is 
dynamic (a dynamic display automatically adjusts its window dimensions 

if the screen size is changed with the SET TERMINAL command). 


Related commands: (SET, CANCEL) DISPLAY, DISPLAY, (SET, CANCEL, 
SHOW WINDOW), SHOW SELECT, EXTRACT/SCREEN_LAYOUT. 
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SHOW DISPLAY 





EXAMPLE 


DBG> SHOW DISPLAY 
display SRC at Hl, size = 64, dynamic 
kind = SOURCE (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC) 
display INST at Hl, size = 64, removed, dynamic 
kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\%PC) 
display REG at RH1, size = 64, removed, dynamic, kind = REGISTER 
display OUT at S45, size = 100, dynamic, kind = OUTPUT 
display EXSUM at Q3, size = 64, dynamic, kind = DO (EXAMINE SUM) 
display PROMPT at S6, size = 64, dynamic, kind = PROGRAM 
DBG> 


The SHOW DISPLAY command lists all displays currently defined. In 
this example, they include the five predefined displays (SRC, INST, REG, 
OUT, and PROMPT), and the user-defined DO display EXSUM. Displays 
INST and REG are removed from the display pasteboard: the DISPLAY 
command must be used in order to display them on the screen. 
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SHOW EDITOR 


SHOW EDITOR 


Indicates the action taken by the EDIT command, as established by the SET 
EDITOR command. 





FORMAT SHOW EDITOR 





DESCRIPTION _ Related commands: SET EDITOR, EDIT. 





EXAMPLES 


DBG> SHOW EDITOR 
The editor is SPAWNed, with command line 
"LSEDIT/START POSITION= (n,1)"™ 
DBG> 


This command indicates that, when you enter the EDIT command, you 
spawn the VAX Language-Sensitive Editor in a subprocess. The /START_ 
POSITION qualifier that is appended to the command line indicates that 
the editing cursor is initially positioned at the beginning of the line that is 
centered in the debugger’s current source display. 


[ND] 


DBG> SET EDITOR/CALLABLE TPU 

DBG> SHOW EDITOR 

The editor is CALLABLE TPU, with command line "TPU" 
DBG> 


In this example, the SHOW EDITOR command indicates that, when you 
enter the EDIT command, you invoke the callable version of the VAX Text 
Processing Utility (VAXTPU). The editing cursor is initially positioned at 
the beginning of source line 1. 
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SHOW EVENT FACILITY 


SHOW EVENT FACILITY 


Identifies the current run-time facility for eventpoints and the associated event 
names. 


Note: This command applies to Ada and SCAN programs. See the VAX 
Ada and VAX SCAN documentation for complete information. 





FORMAT 


SHOW EVENT FACILITY 





DESCRIPTION 


The SHOW EVENT_FACILITY command is meaningful only with Ada or 
CAN programs. The command identifies the current run-time facility and 
lists the associated event names that can be used with the SET BREAK 
/EVENT and SET TRACE/EVENT commands. The event names associated 
with the Ada and SCAN run-time facilities are identified in Appendix E. 


Related commands: SET EVENT_FACILITY, (SET, CANCEL) BREAK 
/EVENT, SHOW BREAK, (SET, CANCEL) TRACE/EVENT, SHOW 
TRACE. 





EXAMPLE 


DBG> SHOW EVENT FACILITY 
event facility is ADA 


DBG> 
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This command identifies the current event facility to be Ada and lists the 
associated event names that can be used with a SET BREAK/EVENT or 
SET TRACE/EVENT command. 


SHOW EXIT HANDLERS 


SHOW EXIT HANDLERS 


Identifies the exit handlers that have been declared in your program. 





FORMAT SHOW EXIT HANDLERS 





DESCRIPTION = The exit handler routines are displayed in the order that they are called 
(that is, last in, first out). The routine name is displayed symbolically, if 
possible. Otherwise, its address is displayed. The debugger’s exit handlers 
are not displayed. 





EXAMPLE 


DBG> SHOW EXI Tl HANDLERS 
exit handler at STACKS\CLEANUP 
DBG> 


This command identifies the exit handler routine CLEANUP, which is 
declared in module STACKS. 
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SHOW IMAGE 


SHOW IMAGE 


Displays information about one or more shareable images that are part of your 
running program. 














FORMAT SHOW IMAGE = /image-name] 
PARAMETERS image-name 
Specifies the name of a shareable image to be included in the display. If 
you do not specify a name, or if you specify the asterisk wildcard character 
(*) by itself, all images are listed. You can use * within an image name. 
DESCRIPTION The SHOW IMAGE command displays the following information: 
e Name of the shareable image 
e Start and end addresses of the image 
¢ Whether the image has been set with the SET IMAGE command 
(loaded into the RST) 
e Current image that is your debugging context (marked with an 
asterisk) 
e Total number of images selected in the display 
¢ Number of bytes allocated for the RST and other internal structures 
Related commands: (SET, CANCEL) IMAGE, (SET, SHOW, CANCEL) 
MODULE. 
EXAMPLE 


DBG> SHOW IMAGE SHARE* 


image name 


* SHARE 
SHAREL 
SHARE2 
SHARE3 
SHARE4 


total images: 5 
DBG> 
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set base address end address 
yes 00000200 QOOOOOFFF 
no 00001000 O000017FF 
yes 00018C00 000191FF 
no 00019200 OO0195FF 
no 00019600 OOO1IBT7FF 


bytes allocated: 33032 


This SHOW IMAGE command identifies all of the shareable images whose 
names start with "SHARE" and which are associated with the program. 
Images SHARE and SHARE2 are set. The asterisk identifies SHARE as 
the current image. 


SHOW KEY 








SHOW KEY 
Displays the debugger predefined key definitions and those created by the 
DEFINE/KEY command. 

FORMAT SHOW KEY _[key-name] 

PARAMETERS’ key-name 
Specifies a function key whose definition is displayed. Do not use the 
asterisk wildcard character (*). Do not specify a key name with /ALL. 
Valid key names are as follows: 

Key-name LK201 Keyboard VT100-type VT52-type 

PF1 PF1 PF1 Blue 

PF2 PF2 PF2 Red 

PF3 PF3 PF3 Black 

PF4 PF4 PF4 

KPO — KP9 Keypad 0 -— 9 Keypad 0 — 9 Keypad 0 —- 9 

PERIOD Keypad period (.) Keypad period (.) 

COMMA Keypad comma (, ) Keypad comma (,) 

MINUS Keypad minus (—) Keypad minus (—) 

ENTER ENTER ENTER ENTER 

E1 Find 

E2 Insert Here 

E3 Remove 

E4 Select 

E5 Prev Screen 

E6 Next Screen 

HELP Help 

DO Do 

F6 — F20 F6 — F20 





QUALIFIERS /ALL 


Displays all key definitions for the current state, by default, or for the 
states specified with the /STATE qualifier. Do not specify a key name with 


/ALL. 


/BRIEF 


Displays only the key definitions (by default, all the qualifiers associated 
with a key definition are also shown, including any specified state). 
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SHOW KEY 


/DIRECTORY 


Displays the names of all the states for which keys have been defined. Do 
not specify other qualifiers with /DIRECTORY. 


/STATE=(state-name [, ... ]) 
/NOSTATE (default) 


Selects one or more states for which a key definition is displayed. The 
/STATE qualifier displays key definitions for the specified states. You 

can specify predefined key states, such as DEFAULT and GOLD, or user- 
defined states. A state name can be any appropriate alphanumeric string. 
The /NOSTATE qualifier displays key definitions for the current state only. 





DESCRIPTION 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use 
this command. Keypad mode is enabled by default. 


By default, the current key state is the "DEFAULT" state. The current 
state can be changed with the SET KEY/STATE command, or by pressing 
a key that causes a state change (a key that was defined with the DEFINE 
/KEY/LOCK_STATE/STATE qualifier combination). 


Related commands: DEFINE/KEY, DELETE/KEY, SET KEY. 





EXAMPLES 


DBG> SHOW KEY/ALL 


This command displays all the key definitions for the current state. 


DBG> SHOW KEY/STATE=BLUE KP8 
GOLD keypad definitions: 
KP8 = "Scroll/Top" (noecho,terminate,nolock) 


DBG> 


This command displays the definition for keypad key 8 in the BLUE state. 


DBG> SHOW KEY/BRIEF KP8 
DEFAULT keypad definitions: 
KP8 = "Scroll/Up" 


DBG> 
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This command displays the definition for keypad key 8 in the current key 
state. 


DBG> SHOW KEY/DIRECTORY 
MOVE GOLD 
MOVE BLUE 
MOVE 

GOLD 

EXPAND GOLD 
EXPAND BLUE 
EXPAND 
DEFAULT 
CONTRACT GOLD 
CONTRACT BLUE 
CONTRACT 

BLUE 

DBG> 


SHOW KEY 


This command displays the names of the states for which keys have been 


defined. 
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SHOW LANGUAGE 


SHOW LANGUAGE 


Identifies the current language. 





FORMAT SHOW LANGUAGE 





DESCRIPTION = The current language is the language last established with the SET 
LANGUAGE command. If no SET LANGUAGE command was entered, 
the current language is, by default, the language of the module containing 
the main program. 


Related commands: SET LANGUAGE. 





EXAMPLE 


DBG> SHOW LANGUAGE 
language: BASIC 
DBG> 


This command displays the name of the current language as BASIC. 
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SHOW LOG 


SHOW LOG 


Indicates whether the debugger is writing to a log file and identifies the current 
log file. 





FORMAT SHOW LOG 





DESCRIPTION The current log file is the log file last established by a SET LOG command. 
If no SET LOG command was entered, the current log file is the file 
SYS$DISK:[ JDEBUG.LOG by default. 


Related commands: SET LOG, SET OUTPUT [NOJLOG, SET OUTPUT 
[NOJSCREEN_LOG. 





EXAMPLES 


DBG> SHOW LOG 
not logging to DEBUG.LOG 
DBG> 


This command displays the name of the current log file as DEBUG.LOG 
(the default log file) and reports that the debugger is not writing to it. 


DBG> SET LOG PROG4 

DBG> SET OUTPUT LOG 

DBG> SHOW LOG 

logging to USERS: [JONES.WORK]PROG4.LOG 
DBG> 


LD | 


In this example, the SET LOG command establishes that the current log 
file is PROG4.LOG (in the current default directory). The SET OUTPUT 
LOG command causes the debugger to log debugger input and output into 
that file. The SHOW LOG command confirms that the debugger is writing 
to the log file PROG4.COM in the current default directory. 


CD-227 


SHOW MARGINS 


SHOW MARGINS 


Identifies the current source-line margin settings for the display of source 
code. 





FORMAT SHOW MARGINS 





DESCRIPTION = The current margin settings are the margin settings last established 
with the SET MARGINS command. If no SET MARGINS command was 
entered, the left margin is set to 1 and the right margin is set to 255 by 
default. 


Related commands: SET MARGINS. 





EXAMPLES 


DBG> SHOW MARGINS 
left margin: 1 , right margin: 255 
DBG> 


This command displays the default margin settings of 1 and 255. 


DBG> SET MARGINS 50 
DBG> SHOW MARGINS 
left margin: 1, right margin: 50 
DBG> 
This command displays the default left margin setting of 1 and the 
modified right margin setting of 50. 
DBG> SET MARGINS 10:60 


DBG> SHOW MARGINS 
left margin: 10 , right margin: 60 
DBG> 


This command displays both margin settings modified to 10 and 60. 
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SHOW MAX_SOURCE FILES 


SHOW MAX SOURCE FILES 


Identifies the maximum number of source files that the debugger can keep 
open at any one time. 





FORMAT SHOW MAX_SOURCE_ FILES 





DESCRIPTION — The maximum number of source files that the debugger can keep open 
at any one time can be specified using the SET MAX _SOURCE_FILES 
command. If no SET MAX _SOURCE_FILES command was entered, the 
maximum number of files is 5 by default. 


Related commands: SET MAX SOURCE_FILES, (SET, SHOW, CANCEL) 
SOURCE. 





EXAMPLE 


DBG> SHOW MAX SOURCE FILES 
max source files: 7 
DBG> 


This command shows that the debugger can keep a maximum of 7 source 
files open at any one time. 
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SHOW MODE 


SHOW MODE 


Identifies the current debugger modes (screen or no screen, keypad or 
nokeypad, and so on) and the current radix. 





FORMAT SHOW MODE 





DESCRIPTION _ The current debugger modes are the modes last established with the SET 
MODE command. If no SET MODE command was entered, the current 
modes are, by default: DYNAMIC, NOG_FLOAT (D_float), INTERRUPT, 
KEYPAD, LINE, NOSCREEN, SCROLL, NOSEPARATE, SYMBOLIC. 


Related commands: (SET, CANCEL) MODE, (SET, SHOW, CANCEL) 
RADIX. 





EXAMPLE 


DBG> SHOW MODE 

modes: symbolic, line, d float, screen, scroll, keypad, 
dynamic, interrupt, no separate window 

input radix :decimal 

output radix:decimal 

DBG> 


The SHOW MODE command displays the current modes and current 
input and output radix. 
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SHOW MODULE 


SHOW MODULE 


Displays information about the modules in the current image. 





FORMAT 


SHOW MODULE /[module-name] 





PARAMETERS 


module-name 

Specifies the name of a module to be included in the display. If you do 
not specify a name, or if you specify the asterisk wildcard character (* ) 
by itself, all modules are listed. You can use * within a module name. 
Shareable image modules are selected only if the /SHARE qualifier is 
specified. 





QUALIFIERS 


/RELATED 


/NORELATED (default) 
Note: This qualifier applies to Ada programs. 


Controls whether the debugger includes, in the SHOW MODULE display, 
any module that is related to a specified module through a with-clause or 
subunit relationship. 


SHOW MODULE/RELATED displays related modules as well as those 
specified. The display identifies the exact relationship. By default 
(/NORELATED), no related modules are selected for display (only the 
modules specified are selected). 


/SHARE 


/NOSHARE (default) 

Controls whether the debugger includes, in the SHOW MODULE display, 
any shareable images that have been linked with your program. By 
default ((NOSHARE) no shareable image modules are selected for display. 


The debugger creates dummy modules for each shareable image in your 
program. The names of these shareable "image modules" have the prefix 
"SHARE$". SHOW MODULE/SHARE identifies these shareable image 
modules, as well as the modules in the current image. 


Setting a shareable image module loads the universal symbols for that 
image into the run-time symbol table so that you can reference these 
symbols from the current image. However, you cannot reference other 
(local or global) symbols in that image from the current image. Note that 
this feature overlaps the effect of the newer SET IMAGE and SHOW 
IMAGE commands. 





DESCRIPTION 


Note: The current image is either the main image (by default) 
or the image established as the current image by a previous SET 
IMAGE command. 
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SHOW MODULE 


The SHOW MODULE command displays the following information about 
one or more modules selected for display: 


e Name of the module. 


e Programming language in which the module is coded, unless all 
modules are coded in the same language. 


e Whether the module has been set with the SET MODULE command. 
That is, whether the symbol records of the module have been loaded 
into the debugger’s run-time symbol table (RST). 


e Space (in bytes) required in the RST for symbol records in that module. 
¢ Total number of modules selected in the display. 


¢ Number of bytes allocated for the RST and other internal structures 
(the amount of heap space in use in the main debugger’s process). 


Related commands: (SET, CANCEL) MODULE, (SET, SHOW, CANCEL) 
IMAGE, SET MODE [NOJDYNAMIC, SHOW SYMBOL, (SET, SHOW, 
CANCEL) SCOPE. 





EXAMPLES 


DBG> SHOW MODULE 
module name 


symbols size 


TEST yes 432 

SCREEN IO no 280 

total PASCAL modules: 2. bytes allocated: 2740. 
DBG> 


DBG> SHOW MODULE 
module name 


FOO 

MAIN 
SUB1 
SUB2 


total modules: 4. 


DBG> 
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In this example, the SHOW MODULE command, without a parameter 
specified, displays information about all of the modules in the current 
image, which is the main image by default. This example shows the 
display format when all modules have the same source language. The 
"symbols" column shows that module TEST has been set, but module 
SCREEN_IO has not. 


FOO, MAIN, SUB* 
symbols language size 


yes MACRO 432 
no FORTRAN 280 
no FORTRAN 164 
no FORTRAN 204 


bytes allocated: 60720. 


In this example, the SHOW MODULE command displays information 

about the modules FOO and MAIN, and all modules having the prefix 
SUB. This example shows the display format when the modules do not 
have the same source language. 


DBG> SHOW MODULE/SHARE 


module name 


FOO 
MAIN 


SHARESDEBUG 
SHARESLIBRTL 
SHARESMTHRTL 
SHARES SHARE1 
SHARES SHARE2 


total modules: 


ie 


symbols 


yes 
no 


no 
no 
no 
no 
no 


DBG> SET MODULE SHARESSHARE2 
DBG> SHOW SYMBOL * IN SHARESSHARE2 


DBG> 


SHOW MODULE 


language size 
MACRO 432 
FORTRAN 280 
Image Q 
Image 0 
Image 0 
Image 0 
Image 0 
162280. 


bytes allocated: 


In this example, the command SHOW MODULE/SHARE identifies all 

of the modules in the current image and all of the shareable images 
(the names of the shareable images are prefixed with "SHARE$"). The 
command SET MODULE SHARE$SHARE2 sets the shareable image 
module SHARE$SHARE2. The SHOW SYMBOL command identifies any 
universal symbols defined in the shareable image SHARE2. 
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SHOW OUTPUT 


Identifies the current output options. 





FORMAT SHOW OUTPUT 





DESCRIPTION _ The current output options are the options last established with the SET 
OUTPUT command. If no SET OUTPUT command was entered, the 


output options are, by default: NOLOG, NOSCREEN_LOG, TERMINAL, 
NOVERIFY. 


Related commands: SET OUTPUT, SET LOG, SET MODE SCREEN. 





EXAMPLE 


DBG> SHOW OUTPUT 
noverify, terminal, screen_log, 

logging to USERS: [JONES.WORK] DEBUG. LOG; 9 
DBG> 


This command shows the following current output options: 


¢ Debugger commands read from debugger command procedures are not 
echoed on the terminal. 


e Debugger output is being displayed on the terminal. 


e The debugging session is being logged to the log file 
USER$:[JONES.WORK]DEBUG.LOG;9. 


e The screen contents are logged as they are updated in screen mode. 
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SHOW PROCESS 


Displays information about processes that are currently under debugger 
control. This command applies especially to a multiprocess debugging 
configuration (when DBG$PROCESS has the value MULTIPROCESS). 





FORMAT SHOW PROCESS [process-specf, ... |] 





PARAMETERS process-spec 


Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name The VMS process name, if that name 
contains no space or lowercase 
characters. The process name can 
include the asterisk wildcard character 
(*). 

[%~PROCESS_NAME] "process-name" The VMS process name, if that 
name contains space or lowercase 
characters. You can also use 
apostrophes (’) instead of quotation 
marks ("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number (or The number assigned to a process 


%PROC process-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 


/PROCESS_GROUP command to 
represent a group of processes. 


%NEXT_PROCESS The process after the visible process in 


the debugger’s circular process list. 
%PREVIOUS_ PROCESS The process previous to the visible 
process in the debugger’s circular 
process list. 
%VISIBLE_PROCESS The process whose call stack, register 


set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk wildcard character (*) to specify all 
processes. If you do not specify a process, the visible process is selected, 
unless you specify /ALL. 





QUALIFIERS /ALL 


Selects all processes known to the debugger for display. Do not specify a 
process with /ALL. 
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/BRIEF 


Displays only one line of information for each process selected for display. 
The /BRIEF qualifier is the default. 


/DYNAMIC 


Shows whether dynamic process setting is enabled or disabled. Dynamic 
process setting is enabled by default and is controlled with the command 
SET PROCESS/[INOJDYNAMIC. 


Do not specify a process with /DYNAMIC. Do not specify /ALL, /BRIEF, 
/FULL, /LNOJHOLD, or /VISIBLE with /DYNAMIC. 


/FULL 


Displays maximum information for each process selected for display. 


/HOLD 
/NOHOLD 


Selects either processes that are on hold, or processes that are not on hold 
for display. 


If you do not specify a process, /HOLD selects all processes that are on 
hold. If you specify a process list, /HOLD selects the processes in the list 
that are on hold. 


If you do not specify a process, /NOHOLD selects all processes that are not 
on hold. If you specify a process list, /NOHOLD selects the processes in 
the list that are not on hold. 


If you specify both /HOLD and /NOHOLD on the same command line, the 
effect is to select processes that are on hold and processes that are not on 
hold for display (the qualifier specified last on the command line does not 
override the other). 


/VISIBLE 


Selects the visible process for display. If you do not specify /VISIBLE, it is 
assumed by default. 





DESCRIPTION 
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The SHOW PROCESS command displays information about specified 
processes and any images running in those processes. 


When used with the /FULL qualifier, the SHOW PROCESS command 
also displays information about the availability and use of the vector 
processor—information that is useful if you are debugging a program that 
uses vector instructions. 


A process can first appear in a SHOW PROCESS display as soon as it 
comes under debugger control. A process can no longer appear in a SHOW ~ 
PROCESS display if it is terminated through an EXIT or QUIT command. 


By default (/BRIEF), one line of information is displayed for each process, 
including as follows: 


¢ The process number assigned by the debugger. A process number is 
assigned sequentially, starting with process 1, to each process that 
comes under debugger control. If a process is terminated by an EXIT 
or QUIT command, its process number is not reused during that 


SHOW PROCESS 


debugging session. The visible process is marked with an asterisk (* ) 
in the leftmost column. 


¢ The VMS process name. 
e Whether the process has been put on hold with a SET PROCESS 


/HOLD command. 


e The current debugging state for that process (see Table CD-1). 


¢ The location (symbolized, if possible) at which execution of the image 
is suspended in that process. 


Table CD-1 Debugging States 


Activated 


Break 

Break on branch 
Break on call 

Break on instruction 
Break on lines 
Break on modify of 
Break on return 
Exception break 


Excep. break preceding 


Interrupted 


Step 
Step on return 


Terminated 


Trace 

Trace on branch 

Trace on call 

Trace on instruction 
Trace on lines 

Trace on modify of 
Trace on return 
Exception trace 

Excep. trace preceding 


Unhandled exception 
Watch of 


The image and its process have just been brought under 
debugger control, either through a DCL RUN/DEBUG 
command, a debugger CONNECT command, a CTRL/Y— 
DEBUG sequence, or by the program signaling SS$_ 
DEBUG while it was not under debugger control. 


A breakpoint was triggered. 


Execution was interrupted in that process, either because 
execution was suspended in another process, or because 
the user interrupted program execution with the abort-key 
sequence (CTRL/C by default). 


A STEP command has completed. 


The image indicated has terminated execution but the 
process is still under debugger control. Therefore, you 
can obtain information about the image and its process. 
You can use the EXIT or QUIT command to terminate the 
process. 


A tracepoint was triggered. 


An unhandled exception was encountered. 
A watchpoint was triggered. 


The SHOW PROCESS/FULL gives additional information about processes 


(see the examples). 
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Related commands: SET PROCESS, EXIT, QUIT, DEFINE/PROCESS_ 
GROUP, CTRL/C, CONNECT. 





EXAMPLES 

DBG_2> SHOW PROCESS 
Number Name Hold State Current PC 
* 2 WTA3: HOLD break SCREEN\SLINE 47 
DBG 2> 


The SHOW PROCESS command, by default, displays one line of 
information about the visible process (which is identified with an asterisk 
in the leftmost column. The process has the VMS process name _WTA3:. 
It is the second process brought under debugger control (process number 


2). It is on hold, and the image’s execution is suspended at a breakpoint at 
line 47 of module SCREEN. 


DBG_2> SHOW PROCESS/FULL %PREVIOUS PROCESS 
Process number: 1 Process name: JONES 1: 
Hold: NO Visible process: NO 
Current PC: TEST VALVES\%LINE L153 
State: interrupted 
PID: 20400885 Owner PID: 00000000 
Current/Base priority: 5/4 Terminal: VTA79: 
Image name: USERS: [JONES.PROG1]TEST VALVES .EXE; 31 
Elapsed CPU time: 0 00:03:17.17 CPU Limit: Infinite 
Buffered I/O Count: 14894 Remaining buffered I/O quota: 80 
Direct I/O Count: 6956 Remaining direct I/O quota: 40 
Open file count: 7 Remaining open file quota: 43 
Enqueue count: 200 Remaining enqueue quota: 198 
Vector capable: Yes 
Vector consumer: Yes Vector CPU time: 00:00:00.00 
Fast Vector context switches: 0 Slow Vector context switches: 0 
Current working set size: 1102 Working set size quota: 1304 
Current working set extent: 12288 Maximum working set extent: 12288 
Peak working set size: 4955 Maximum authorized working set: 1304 
Current virtual size: 255 Peak virtual size: 16182 
Page faults: 41358 
Active ASTs: Remaining AST Quota: ZI 
Event flags: FF800000 60000003 Event flag wait mask: 7EFFFFFE 
DBG 2> 
The command SHOW PROCESS/FULL %PREVIOUS_PROCESS displays 
the maximum level of information about the previous process in the | 
circular list of processes (process number 1, in this case). 
DBG_2> SHOW PROCESS %PROCESS NAME TEST 3 


Number Name Hold State Current PC 
? TEST. 3 watch of TEST 3\ROUT4\COUNT 
TEST 3\%SLINE 54 
DBG 2> 


This SHOW PROCESS command displays one line of information about 
process TEST_3. The image is suspended at a watchpoint of variable 
COUNT. 
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Ao DBG _2> SHOW PROCESS/DYNAMIC 
Dynamic process setting is enabled 
DBG 2> 


This SHOW PROCESS/DYNAMIC command indicates that dynamic 
process setting is enabled. 
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SHOW RADIX 


Identifies the current radix for the entry and display of integer data or, if the 
/OVERRIDE command qualifier is specified, the current override radix. 





FORMAT 


SHOW RADIX 





QUALIFIERS 


/OVERRIDE 


Identifies the current override radix. 





DESCRIPTION 


The debugger can interpret and display integer data in any one of four 
radixes: binary, decimal, hexadecimal, and octal. The current radix for 
the entry and display of integer data is the radix last established with the 
SET RADIX command. If no SET RADIX command was entered, the radix 
for both entry and display (input radix and output radix, respectively) is 
decimal for all languages except BLISS and MACRO. It is hexadecimal for 
BLISS and MACRO. 


The current override radix for the display of all data is the override radix 
last established with the SET RADIX/OVERRIDE command. If no SET 
RADIX/OVERRIDE command was entered, the override radix is "none". 


Related commands: (SET, CANCEL) RADIX, EXAMINE, DEPOSIT, 
EVALUATE. 





EXAMPLES 


DBG> SHOW RADIX 


input radix: decimal 


output radix: 
DBG> 


i 


decimal 


This command identifies the input radix and output radix as decimal. 


DBG> SET RADIX/OVERRIDE HEX 


DBG> SHOW RADIX/OVERRIDE 
output override radix: hexadecimal 


DBG> 
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In this example, the SET RADIX/OVERRIDE command sets the override 
radix to hexadecimal and the SHOW RADIX/OVERRIDE command 
indicates the override radix. This means that all data is displayed as 
hexadecimal integer data in commands such as EXAMINE and so on. 


SHOW SCOPE 


SHOW SCOPE 


Identifies the current scope search list for symbol lookup. 





FORMAT 


SHOW SCOPE 





DESCRIPTION 


The current scope search list designates one or more program locations 
(specified by path names or other special characters) to be used in the 
interpretation of symbols that are specified without path name prefixes in 
debugger commands. 


The current scope search list is the scope search list last established with 
the SET SCOPE command. If no SET SCOPE command was entered, the 
current scope search list is 0,1,2, ... ,n by default. 


The default scope search list specifies that, for a symbol without a path 
name prefix, a symbol lookup such as "EXAMINE X" first looks for X in 
the routine that is currently executing (scope 0); if no X is visible there, 
the debugger looks in the caller of that routine (scope 1), and so on down 
the call stack; if X is not found in scope n, the debugger searches the rest 
of the run-time symbol table (RST)—that is, all set modules and the global 
symbol table (GST), if necessary. 


If you have used a decimal integer in the SET SCOPE command to 
represent a routine in the call stack, the SHOW SCOPE command displays 
the name of the routine represented by the integer, if possible. 


Related commands: (SET, CANCEL) SCOPE. 





EXAMPLES 


fl §DBG> CANCEL SCOPE 


DBG> SHOW SCOPE 
scope: 
* 


NOP WHF © 


DBG> 
DBG> 


scope: 


NOwWNE © 


wea eon" PS Oe ee oe oe 


rit ug bt on 


SET 


[es Oe ce cee tees ee ee Oe ee 


todo Wt wo be u 


EIGHTQUEENS\TRYCOL\REMOVEQUEEN J], 
EIGHTQUEENS\TRYCOL ], 
EIGHTQUEENS\TRYCOL 1 ], 
EIGHTQUEENS\TRYCOL 2 ], 
EIGHTQUEENS\TRYCOL 3 ], 
EIGHTQUEENS\TRYCOL 4 J, 
EIGHTQUEENS ] 

SCOPE/CURRENT 2 

SHOW SCOPE 


EIGHTQUEENS\TRYCOL\REMOVEQUEEN ], 
EIGHTQUEENS\TRYCOL J, 
EIGHTQUEENS\TRYCOL 1 J, 
EIGHTQUEENS\TRYCOL 2 J, 
EIGHTQUEENS\TRYCOL 3 J, 
FIGHTQUEENS\TRYCOL 4 ], 
EIGHTQUEENS ] 
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The CANCEL SCOPE command restores the default scope search list, 
which is displayed by the (first) SHOW SCOPE command. In this 
example, execution is suspended at routine REMOVEQUEEN, after 
several recursive calls to routine TRYCOL. The asterisk indicates that 
the scope search list starts with scope 0, the scope of the routine in which 
execution is suspended. 


The command SET SCOPE/CURRENT resets the start of the scope search 
list to scope 2. Scope 2 is the scope of the caller of the caller of the routine 
in which execution is suspended. The asterisk in the output of the (second) 
SHOW SCOPE command indicates that the scope search list now starts 
with scope 2. 


DBG> SET SCOPE 0,STACKS\R2,SCREEN_ IO, \ 


DBG> SHOW SCOPE 


scope: 


0, [= TEST ]j, 


STACKS\R2, 
SCREEN IO, 
\ 

DBG> 
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In this example, the SET SCOPE command directs the debugger to 

look for symbols without path name prefixes according to the following 
scope search list. First the debugger looks in the PC scope (denoted by 
"QO", which is in module TEST). If the debugger cannot find a specified 
symbol in the PC scope, it then looks in routine R2 of module STACKS; 
if necessary, it then looks in module SCREEN_IO, and then finally in the 
global symbol table (denoted by the global scope, \). The SHOW SCOPE 
command identifies the current scope search list for symbol lookup. Note 
that no asterisk is shown in the SHOW SCOPE display unless the default 
scope search list is in effect or you have previously entered a SET SCOPE 
/CURRENT command. 


SHOW SEARCH 


SHOW SEARCH 


Identifies the default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) 
currently in effect for the SEARCH command. 





FORMAT SHOW SEARCH 





DESCRIPTION The default qualifiers for the SEARCH command are the default qualifiers 
last established with the SET SEARCH command. If no SET SEARCH 
command was entered, the default qualifiers are /NEXT and /STRING. 


Related commands: SET SEARCH, SEARCH, (SET, SHOW) LANGUAGE. 





EXAMPLE 


DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 

DBG> SET SEARCH IDENT 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 

DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 
DBG> 


In this example, the first SHOW SEARCH command displays the default 
settings for the SET SEARCH command. By default, the debugger 
searches for and displays the next occurrence of the string. 


The second SHOW SEARCH command indicates that the debugger 
searches for the next occurrence of the string, but displays the string 
only if it is not bounded on either side by a character that can be part of 
an identifier in the current language. 


The third SHOW SEARCH command indicates that the debugger searches 
for all occurrences of the string, but displays the strings only if they are 
not bounded on either side by a character that can be part of an identifier 
in the current language. 
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SHOW SELECT 


Identifies the displays currently selected for each of the display attributes: 
error, input, instruction, output, program, prompt, scroll, and source. 





FORMAT SHOW SELECT 





DESCRIPTION The display attributes have the following properties: 


e A display that has the error attribute displays debugger diagnostic 
messages. 


e A display that has the input attribute echoes your debugger input. 


e A display that has the instruction attribute displays the decoded 
assembly language instruction stream of the routine being debugged. 
The display is updated when you enter an EXAMINE/INSTRUCTION 
command. 


e A display that has the output attribute displays any debugger output 
that is not directed to another display. 


¢ A display that has the program attribute displays program input and 
output. Currently only the PROMPT display can have the program 
attribute. 


e A display that has the prompt attribute is where the debugger prompts 
for input. Currently, only the PROMPT display can have the PROMPT 
attribute. 


e A display that has the scroll attribute is the default display for the 
SCROLL, MOVE, and EXPAND commands. 


e Adisplay that has the source attribute displays the source code of the 
module being debugged, if available. The display is updated when you 
enter a TYPE or EXAMINE/SOURCE command. 


Related commands: SELECT, SHOW DISPLAY. 





EXAMPLE 


DBG> SHOW SELECT 
display selections: 


scroll = SRC 
input = none 
output = OUT 
error = PROMPT 
source = SRC 


instruction = none 

program = PROMPT 

prompt = PROMPT 
DBG> 
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In this example, The SHOW SELECT command identifies the displays 
currently selected for each of the display attributes. The display selections 
shown are the default selections for all languages. 


CD-245 


SHOW SOURCE 


SHOW SOURCE 


Identifies the source directory search lists currently in effect. 
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FORMAT SHOW SOURCE 

QUALIFIERS /EDIT 
Note: This qualifier applies mainly to Ada programs. 
Identifies the search list for source files to be edited when you use the 
EDIT command. 

DESCRIPTION _ Ifa source directory search list has not been established by means of 


the SET SOURCE or SET SOURCE/MODULE=module-name commands, 
the SHOW SOURCE command indicates that no directory search list is 
currently in effect. In this case, the debugger expects each source file to 
be in the same directory that it was in at compile time (the debugger also 
checks that the version number and the creation date and time of a source 
file match the information in the debugger’s symbol table). 


The SET SOURCE/MODULE=module-name command establishes a source 
directory search list for a particular module. The SET SOURCE command 
establishes a source directory search list for all modules not explicitly 
mentioned in a SET SOURCE/MODULE=module-name command. When 
those commands have been used, the SHOW SOURCE command identifies 
the source directory search list associated with each search categories. 


The /EDIT qualifier is needed when the files used for the display of source 
code are different from the files to be edited by means of the EDIT 
command. This is the case with Ada programs. For Ada programs, the 
SHOW SOURCE command identifies the search list of files used for source 
display (the "copied" source files in Ada program libraries); the SHOW 
SOURCE/EDIT command identifies the search list for the source files you 
edit when using the EDIT command. 


Related commands: (SET, CANCEL) SOURCE, (SET, SHOW) MAX_ 
SOURCE_FILES. 


SHOW SOURCE 





EXAMPLES 


DBG> SHOW SOURCE 
no directory search list in effect 
DBG> SET SOURCE [PROJA], [PROJB],DISK: [PETER.PROJC] 
DBG> SHOW SOURCE 
source directory search list for all modules: 
[PROJA] 
[PROJB] 
DISK: [PETER.PROJC] 
DBG> 


In this example, the SET SOURCE command directs the debugger to 
search the directories [PROJA],[PROJB], and DISK:[PETER.PROJC]. 


DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2: [PROUD] 
DBG> SHOW SOURCE 
source directory search list for COBOLTEST: 
[] 
DISKS2: [PROJD] 
source directory search list for all other modules: 
{PROJA] 
[PROJB] 
DISK: [PETER.PROJC] 
DBG> | 


In this example, the SET SOURCE command directs the debugger to 
search the current default directory ([]) and directory DISK$2:[PROJD] for 
source files to use with the module COBOLTEST. 
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SHOW STACK 


Displays information from the current call stack. 





FORMAT SHOW STACK /n/ 





PARAMETERS 7! 


Specifies the number of frames to display. If n is omitted, information 
about all call stack frames is displayed. 





DESCRIPTION _ For each call frame, the SHOW STACK command displays information 
such as the condition handler, saved register values, and the argument 
list, if any. The latter is the list of arguments passed to the subroutine 
with that call. In some cases the argument list can contain the addresses 
of actual arguments. In such cases, use the command EXAMINE address 
to display the values of these arguments. 


Related commands: SHOW CALLS. 





EXAMPLE 


DBG> SHOW STACK 
stack frame 0 (2146814812) 


condition handler: 0 


SPA: 0 

Ss: e) 

mask: A“AM<R2> 

PSW: 0000 (hexadecimal) 
saved AP: A 
saved FP: | 2146814852 
saved PC: EIGHTQUEENS\%SLINE 69 
saved R2: 0 


argument list:(1) EIGHTQUEENS\%SLINE 68+2 
stack frame 1 (2146814852) 
condition handler: SHARESPASRTL+888 


SPA: @) 

S: 0 

mask: none saved 

PSW: 0000 (hexadecimal) 
saved AP: 2146814924 
saved FP: 2146814904 
saved PC: | SHARESDEBUG+667 


DBG> 


In this example, the SHOW STACK command displays information about 
all call stack frames at the current PC location. 
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SHOW STEP 


Identifies the default qualifiers (INTO, /INSTRUCTION, /NOSILENT and so 
on) currently in effect for the STEP command. 





FORMAT SHOW STEP 





DESCRIPTION = The default qualifiers for the STEP command are the default qualifiers 
last established by the SET STEP command. If no SET STEP command 
was entered, the default qualifiers are /LINE, /OVER, /NOSILENT, and 
/SOURCE. 


If you invoke screen mode with the keypad-key sequence PF1-PF3, the 
command SET STEP NOSOURCE is issued in addition to the command 
SET MODE SCREEN (to eliminate redundant source display in output 
and DO displays). In that case, the default qualifiers for the STEP 
command are /LINE, /OVER, /NOSILENT, and /NOSOURCE. 


Related commands: SET STEP, STEP. 





EXAMPLE 


DBG> SET STEP INTO, NOSYSTEM, NOSHARE, INSTRUCTION, NOSOURCE 
DBG> SHOW STEP 


step type: nosystem, noshare, nosource, nosilent, into routine calls, 
by instruction 
DBG> 


In this example, the SHOW STEP command indicates that the debugger 
take the following action: 


e Steps into called routines, but not those in system space or in 
shareable images 


e Steps by instruction 


¢ Does not display lines of source code while stepping 
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SHOW SYMBOL 


Displays information about the symbols in the debugger’s run-time symbol 
table (RST) for the current image. 





FORMAT SHOW SYMBOL  symbol-namef, ... ] [IN 
scopef,... ]] 





PARAMETERS symbol-name 


Specifies a symbol to be identified. A valid symbol name is a single 
identifier or a label name of the form 2ZLABEL n, where n is an integer. 
Compound names such as RECORD.FIELD or ARRAY[1,2] are not valid. 
If you specify the asterisk wildcard character (*) by itself, all symbols are 
listed. You can use * within a symbol name. 


scope 

Specifies the name of a module, routine, or lexical block, or a numeric 
scope. It has the same syntax as the scope specification in a SET SCOPE 
command and can include path name qualification. All specified scopes 
must be in set modules in the current image. 


The SHOW SYMBOL command displays only those symbols in the RST 
for the current image that both match the specified name and are declared 
within the lexical entity specified by the scope parameter. If the scope 
parameter is omitted, all set modules and the global symbol table (GST) 
for the current image are searched for symbols that match the name 
specified by the symbol-name parameter. 





QUALIFIERS /ADDRESS 
Displays the address specification for each selected symbol. The address 
specification is the method of computing the symbol’s address. It 
can merely be the symbol’s memory address, but it can also involve 
indirection or an offset from a register value. Some symbols have address 
specifications too complicated to present in any understandable way. These 
address specifications are labeled "complex address specifications." 


/DEFINED 


Displays symbols you have defined with the DEFINE command (symbol 
definitions that are in the DEFINE symbol table). 


/DIRECT 


Displays only those symbols that are declared directly in the scope 
parameter. Symbols declared in lexical entities nested within the scope 
specified by the scope parameters are not shown. 


/LOCAL 


Displays symbols that are defined with the DEFINE/LOCAL command 
(symbol definitions that are in the DEFINE symbol table). 
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/TYPE 


Displays data type information for each selected symbol. 


/USE_CLAUSE 


Note: This qualifier applies to Ada programs. 


Identifies any Ada package that a specified block, subprogram, or package 
names in a use clause. If the symbol specified is a package, also identifies 
any block, subprogram, package, and so on that names the specified 
symbol in a use clause. 





DESCRIPTION 


Note: The current image is either the main image (by default) 
or the image established as the current image by a previous SET 
IMAGE command. 


The SHOW SYMBOL command displays information that the debugger 
has about a given symbol in the current image. This information might 
not be the same as what the compiler had or even what you see in your 
source code. Nonetheless, it is useful for understanding why the debugger 
might act as it does when handling symbols. 


If you do not specify a qualifier, the SHOW SYMBOL command lists all 
of the possible declarations or definitions of a specified symbol that exist 
in the RST for the current image—that is, in all set modules and in the 
GST for that image. Symbols are displayed with their path names. A 
path name identifies the search scope (module, nested routines, blocks, 
and so on) that the debugger must follow to reach a particular declaration 
of a symbol. When specifying symbolic address expressions in debugger 
commands, you need to use path names only if a symbol is defined multiple 
times and the debugger cannot resolve the ambiguity. 


The /DEFINED and /LOCAL qualifiers display information about symbols 
defined with the DEFINE command (not the symbols that are derived from 
your program). The other qualifiers display information about symbols 
defined within your program. 


Related commands: DEFINE, SHOW DEFINE, DELETE, SYMBOLIZE, 
SET MODE [NO]LINE, SET MODE [NO]JSYMBOLIC. 





EXAMPLES 


DBG> SHOW SYMBOL I 


data FORARRAY\I 


DBG> 


This command shows that symbol I is defined in module FORARRAY and 
is a variable (data) rather than a routine. 


DBG> SHOW SYMBOL/ADDRESS INTARRAY1 
data FORARRAY\INTARRAY1 
descriptor address: QOO9DE8B 


DBG> 


This command shows that symbol INTARRAY1 is defined in module 
FORARRAY and has a memory address of 0009DE8B. 
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DBG> SHOW SYMBOL *PL* 
This command lists all the symbols whose names contain the string "PL". 
DBG> SHOW SYMBOL/TYPE/ADDRESS * 
This command displays all information about all symbols. 


DBG> SHOW SYMBOL * IN MOD3\COUNTER 
routine MOD3\COUNTER 
data MOD3\COUNTER\X 
data MOD3\COUNTER\Y 

DBG> 


This command lists all the symbols that are defined in the scope denoted 
by the path name MOD3\ COUNTER. 


DBG> DEFINE/COMMAND SB=SET BREAK 
DBG> SHOW SYMBOL/DEFINED SB 
defined SB 

bound to: SET BREAK 

was defined /command 
DBG> 


In this example, the DEFINE/COMMAND command defines SB as a 
symbol for the command SET BREAK. The SHOW SYMBOL/DEFINED 
command displays that definition. 
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SHOW TASK 


Displays information about the tasks of a tasking program. 


Note: This command applies to Ada programs. See the VAX Ada 
documentation for complete information. 





FORMAT 


SHOW TASK [task-specf, ... ]] 





PARAMETERS 


task-spec 


Specifies a task value. Use any of the following forms: 


e An Ada language expression for a task value—for example, a task 
object name. You can use a path name. 


¢ The task ID (for example, %TASK 2), as indicated in a SHOW TASK 
display. 


e A task built-in symbol (ZACTIVE_TASK, 2%CALLER_TASK, %NEXT_ 
TASK, or ®VISIBLE_TASK). 


Do not use the asterisk wildcard character (*). See the qualifier 
descriptions for details on how to specify tasks with particular qualifiers. 





QUALIFIERS 


/ALL 


Selects all tasks that currently exist in the program for display. Do not 
specify a task with /ALL. 


/CALLS[=n] 

Performs a SHOW CALLS command for each task selected for display. You 
can use the SHOW CALLS command to obtain the current PC value of a 
task. 


/FULL 


Displays additional information about each task selected for display. The 
/FULL qualifier provides additional information if used either by itself, or 
with the /CALLS or /STATISTICS qualifier. 


/HOLD 
/NOHOLD 


Selects either tasks that are on hold, or tasks that are not on hold for 
display. 


If you do not specify a task, /HOLD selects all tasks that are on hold. If 
you specify a task list, /HOLD selects the tasks in the task list that are on 
hold. 


If you do not specify a task, /NOHOLD selects all tasks that are not on 
hold. If you specify a task list, /NOHOLD selects the tasks in the task list 
that are not on hold. 
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/PRIORITY=(n{, .. . ]) 


If you do not specify a task, selects all tasks that have any of the specified 
priorities, n, where n is a decimal integer from 0 to 15 inclusive. If you 
specify a task list, selects the tasks in the task list that have any of the 
priorities specified. 


/STATE=(statef, ... ]) 

If you do not specify a task, selects all tasks that are in any of the specified 
states (the possible states are RUNNING, READY, SUSPENDED, or 
TERMINATED). If you specify a task list, selects the tasks in the task list 
that are in any of the states specified. 


/STATISTICS 

Displays tasking statistics for the entire tasking system. You can use this 
information to measure the performance of your tasking program. The 
larger the number of total schedulings (also known as context switches), 
the more tasking overhead there is. When you specify /STATISTICS, the 
only other permissible qualifier is /FULL. 


/TIME SLICE 
Displays the current value of pragma TIME_SLICE. 








DESCRIPTION You can select tasks for display with the SHOW TASK command by 
specifying any of the following entities: 
e A task list—that is, a list of task specifications. 
e Task selection qualifiers: /ALL, /[NOJHOLD, /PRIORITY, /STATE. 
e Both a task list and task selection qualifiers. Only the tasks that 
satisfy all specified criteria are selected for display. 
If no task parameters or task selection qualifiers are given, the SHOW 
TASK command displays summary information about the visible task. 
Related commands: SET TASK, SET BREAK/EVENT, SET TRACE 
_ [EVENT, EXAMINE/TASK, DEPOSIT/TASK. 
EXAMPLES 
DBG> SHOW TASK/ALL 
task id pri hold state substate task object 
* STASK 1 a RUN 122624 
STASK 2 7 HOLD SUSP Accept H4.MONITOR 
STASK 3 6 READY Entry call H4.CHECK IN 
DBG> 
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In this example, the SHOW TASK/ALL command provides basic 
information about all the tasks of a program that are currently in 
existence—namely, tasks that have been created and whose master has 
not yet terminated. One line is devoted to each task. The active task is 
marked with an asterisk and is always the task that is in the RUN state. 


DBG> 


DBG> 


DBG> 


DBG> 


DBG> 


SHOW 


SHOW 


SHOW 


SHOW 


SHOW 


SHOW TASK 


TASK sACTIVE TASK, <TASK 3,MONITOR 


This command selects the active task, %TASK 3, and task MONITOR for 
display. 


TASK/PRIORITY=6 
This command selects all tasks with priority 6 for display. 
TASK/STATE= (RUN, SUSP) 


This command selects all tasks that are either running or suspended for 
display. 


TASK/STATE=SUSP /NOHOLD 


This command selects all tasks that are both suspended and not on hold 
for display. 


TASK/STATE= (RUN, SUSP) /PRIO=7 %VISIBLE TASK, %TASK 3 


This command selects for display those tasks among the visible task and 
%TASK 3 that are in either the RUNNING or SUSPENDED STATE, and 
have priority 7. 
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SHOW TERMINAL 


Identifies the current terminal screen height (page) and width being used to 
format output. 





FORMAT SHOW TERMINAL 





DESCRIPTION The current terminal screen height and width are the height and width 
last established by the SET TERMINAL command. If no SET TERMINAL 
command was entered, the current height and width are, by default, the 
height and width known to the VMS terminal driver, as displayed by the 
DCL command SHOW TERMINAL (usually 24 lines and 80 columns, 
respectively, for VT-series terminals). 


Related commands: SET TERMINAL, SHOW DISPLAY, SHOW WINDOW. 





EXAMPLE 


DBG> SHOW TERMINAL 
terminal width: 80 

page: 24 
DBG> 


This command displays the current terminal screen width and height 
(page) as 80 columns and 24 lines, respectively. 
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SHOW TRACE 


Displays information about tracepoints. 





FORMAT SHOW TRACE 





QUALIFIERS /PREDEFINED 


Displays information about predefined tracepoints. 


/USER 


Displays information about user defined tracepoints. 





DESCRIPTION The SHOW TRACE command displays information about tracepoints that 


are currently set, including any options such as WHEN or DO clauses, 
/AFTER counts, and so on. 


By default, SHOW TRACE displays information about both user defined 
and predefined tracepoints (if any). This is equivalent to entering the 
command SHOW TRACE/USER/PREDEFINED. User defined tracepoints 
are set with the SET TRACE command. Predefined tracepoints are set 
automatically when you invoke the debugger, and they depend on the 
type of program you are debugging. See Chapter 10 for information about 
predefined tracepoints that are associated with multiprocess programs. 


If you established a tracepoint using the /AFTER:n command qualifier 
with the SET TRACE command, the SHOW TRACE command displays 
the current value of the decimal integer n, that is, the originally specified 
integer value minus one for each time the tracepoint location was reached. 
(The debugger decrements n each time the tracepoint location is reached 
until the value of n is zero, at which time the debugger takes trace action.) 


Related commands: (SET, CANCEL) TRACE. 





EXAMPLES 


DBG> SHOW TRACE 
tracepoint at routine CALC\MULT 
tracepoint on calls: 
RET RSB BSBB JSB BSBW CALLG CALLS 
DBG> 


The SHOW TRACE command identifies all tracepoints that are currently 
set. This example indicates user defined tracepoints that are triggered 
whenever execution reaches routine MULT in module CALC or one of the 
instructions RET, RSB, BSBB, JSB, BSBW, CALLG, or CALLS. 
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DBG_2> SHOW TRACE/PREDEFINED 
predefined tracepoint on program activation 
DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_/SUF=PROCESS NU AT H1 SOURCE 
(EXAM/SOURCE .%SOURCE_ SCOPE\%PC) ; 
SET DISP/DYN/REM/SIZE:64/PROC INST _/SUF=PROCESS NU AT H1 INST 

(EXAM/INSTRUCTION .O\%PC) ) 

predefined tracepoint on program termination 

DBG 2> 


This command identifies the predefined tracepoints that are currently set. 
The example shows the predefined tracepoints that are set automatically 
by the debugger for a multiprocess program (when DBG$PROCESS 

has the value MULTIPROCESS). The tracepoint on program activation 
triggers whenever a new process comes under debugger control. The 

DO clause creates a process-specific source display named SRC_n and a 
process-specific instruction display named INST_n whenever a process 
activation tracepoint is triggered. The tracepoint on program termination 
triggers whenever a process performs an image exit. 
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SHOW TYPE 


Identifies the current type for program locations that do not have a compiler 
generated type or, if the /OVERRIDE command qualifier is specified, the 
current override type. 





FORMAT SHOW TYPE 





QUALIFIERS /OVERRIDE 


Identifies the current override type. 





DESCRIPTION = The current type for program locations that do not have a compiler 
generated type is the type last established by the SET TYPE command. 
If no SET TYPE command was entered, the type for those locations is 
longword integer. 7 


The current override type for all program locations is the override type 
last established by the SET TYPE/OVERRIDE command. If no SET TYPE 
/OVERRIDE command was entered, the override type is "none". 


Related commands: SET TYPE, CANCEL TYPE/OVERRIDE, (SET, 
SHOW, CANCEL) RADIX, (SET, SHOW, CANCEL) MODE, EXAMINE, 
DEPOSIT. 





EXAMPLES 


DBG> SET TYPE QUADWORD 
DBG> SHOW TYPE 
type: quadword integer 
DBG> 


This command sets the type for locations that do not have a compiler 
generated type to quadword. The SHOW TYPE command displays the 
current default type for those locations as quadword integer. This means 
that the debugger interprets and displays entities at those locations as 
quadword integers unless you specify otherwise (for example with a type 
qualifier on the EXAMINE command). 


LO | 


DBG> SHOW TYPE/OVERRIDE 
type/override: none 
DBG> 


This command indicates that no override type has been defined. 
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SHOW VECTOR MODE 


Note: This command applies to vectorized programs. 
Identifies the current vector mode (synchronized or nonsynchronized). 





FORMAT SHOW VECTOR_MODE | 





DESCRIPTION = The current vector mode is the mode established with the SET VECTOR_ 
MODE command. If no SET VECTOR_MODE command was entered, the 
vector mode is, by default, nonsynchronized. 


Related commands: SET VECTOR_MODE [NO]JSYNCHRONIZED, 
SYNCHRONIZE VECTOR_MODE. 





EXAMPLE 


DBG> SHOW VECTOR MODE 

Vector mode is nonsynchronized 
DBG> SET VECTOR MODE SYNCHRONIZED 
DBG> SHOW VECTOR MODE 

Vector mode is synchronized 

DBG> 


The SHOW VECTOR MODE command indicates the effect of the SET 
VECTOR _ MODE command. 
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SHOW WATCH 


Displays information about watchpoints. 





FORMAT SHOW WATCH 





DESCRIPTION i $The SHOW WATCH command displays information about watchpoints 
that are currently set, including any options such as WHEN or DO clauses, 
/AFTER counts, and so on. 


If you established a watchpoint using the /AFTER:n command qualifier 
with the SET WATCH command, the SHOW WATCH command displays 
the current value of the decimal integer n, that is, the originally specified 
integer value minus one for each time the watchpoint location was 
reached. (The debugger decrements n each time the watchpoint location 
is reached until the value of n is zero, at which time the debugger takes 
watch action.) 


Related commands: (SET, CANCEL) WATCH. 





EXAMPLE 


DBG> SHOW WATCH 

watchpoint of MAIN\X 
watchpoint of SUB2\TABLE+20 
DBG> 


This command displays two watchpoints, one at the variable X (defined in 
module MAIN), and the other at the location SUB2\ TABLE+20 (20 bytes 
beyond the address denoted by the address expression TABLE). 
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SHOW WINDOW 


Identifies the name and screen position of predefined and user-defined 
screen-mode windows. 





FORMAT SHOW WINDOW  [wname/, ... J] 





PARAMETERS Whame 


Specifies the name of a screen window definition. If you do not specify a 
name, or if you specify the asterisk wildcard character (*) by itself, all 
window definitions are listed. You can use * within a window name. Do 
not specify a window definition name with /ALL. 





QUALIFIERS /ALL 


Lists all window definitions. Do not specify a window definition name with 
/ALL. 





DESCRIPTION _ Related commands: (SET, CANCEL) WINDOW, (SET, SHOW, CANCEL) 
DISPLAY, SHOW SELECT, (SET, SHOW) TERMINAL. 





EXAMPLE 


DBG> SHOW WINDOW LH*,RH* 
window LH1 at (1,11,1,40) 
window LH12 at (1,23,1,40) 
window LH2 at (13,11,1,40) 
window RH1 at (1,11, 42,39) 
window RH12 at (1,23, 42,39) 
window RH2 at (13,11, 42,39) 
DBG> 


This command displays the name and screen position of all screen window 
definitions whose names starts with LH or RH. 
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SPAWN 


Creates a subprocess, enabling you to execute DCL commands without 
terminating a debugging session or losing your debugging context. 





FORMAT 


SPAWN [DCL-command] 





PARAMETERS 


DCL-command 

Specifies a DCL command. If you specify a DCL command, the command 
is executed in a subprocess. Control is returned to the debugging session 
when the DCL command terminates. 


If you do not specify a DCL command, a subprocess is created and you can 
then enter DCL commands. Either logging out of the spawned process or 
attaching to the parent process (with the DCL ATTACH command) enables 
you to continue your debugging session. 


If the DCL command contains a semicolon, you must enclose the command 
in quotation marks ("). Otherwise the semicolon is interpreted as a 
debugger command separator. To include a quotation mark inside the 
string, enter two consecutive quotation marks ("" ). 





QUALIFIERS 


AINPUT=tTile-spec 

Specifies an input DCL command file containing one or more DCL 
commands to be executed by the spawned subprocess. The default file 
type is .COM. If you specify a DCL command string with the SPAWN 
command and an input file with the /INPUT qualifier, the command string 
is processed before the input file. After processing of the input file is 
complete, the subprocess is terminated. Do not use the asterisk wildcard 
character (*) in the file specification. 


/OUTPUT=file-spec 

Writes the output from the SPAWN operation to the specified file. The 
default file type is .LOG. Do not use the asterisk wildcard character (*) in 
the file specification. | 


/WAIT (default) 
/NOWAIT 


Controls whether the debugging session (the parent process) is suspended 
while the subprocess is running. The /WAIT qualifier (default) suspends 
the debugging session until the subprocess is terminated. You cannot 
enter debugger commands until control returns to the parent process. 


The /NOWAIT qualifier executes the subprocess in parallel with the 
debugging session. You can enter debugger commands while the 
subprocess is running. If you use /NOWAIT, you should specify a DCL 
command with the SPAWN command; the DCL command is executed 
in the subprocess. A message indicates when the spawned subprocess 
completes. 
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DESCRIPTION 


The SPAWN command acts exactly like the DCL SPAWN command. You 
can edit files, compile programs, read mail, and so on without ending your 
debugging session or losing your current debugging context. 


In addition, you can spawn a DCL SPAWN command. DCL processes 
the second SPAWN command, including any qualifier specified with that 
command. 


Related commands: ATTACH. 





EXAMPLES 


DBG> SPAWN 
$ 


This command shows that the SPAWN command, with no parameter 
specified, creates a subprocess at DCL level. You can now enter DCL 
commands. Log out to return to the debugger prompt. 


2 DBG> SPAWN/NOWAIT/INPUT=READ NOTES/OUTPUT=0428NOTES 


DBG> 


This command creates a subprocess that is executed in parallel with the 
debugging session. This subprocess executes the DCL command procedure 
READ _NOTES.COM. The output from the spawned operation is written to 
the file 0428NOTES.LOG. 


3 DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM 


DBG> 
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This command creates a subprocess that is executed in parallel with 
the debugging session. This subprocess creates another subprocess to 
execute the DCL command procedure MYCOM.COM. The output from 
that operation is written to the file MYCOM.LOG. 


STEP 





Executes the program up to the next line, instruction, or other specified 
location. 
FORMAT STEP [n] 





PARAMETERS /) 


A decimal integer that specifies the number of step units (lines, 
instructions, and so on) to be executed. If you do not specify the parameter 
n, the debugger executes one step unit. 





QUALIFIERS 


/BRANCH 
Executes the program to the next branch instruction. STEP/BRANCH has 
the same effect as SET BREAK/TEMPORARY/BRANCH;GO. 


/CALL 


Executes the program to the next call or RET instruction. STEP/CALL 
has the same effect as SET BREAK/TEMPORARY/CALL;GO. 


/EXCEPTION 

Executes the program to the next exception, if any. STEP/EXCEPTION 
has the same effect as SET BREAK/TEMPORARY/EXCEPTION;GO. If no 
exception occurs, STEP/EXCEPTION has the same effect as GO. 


AINSTRUCTION[=(opcodef, . . . ])] 

If you do not specify an opcode, executes the program to the next 
instruction. STEP/INSTRUCTION has the same effect as SET BREAK 
/TEMPORARY/INSTRUCTION;GO. 


If you specify one or more opcodes, executes the program to 

the next instruction whose opcode is specified in the list. STEP 
JINSTRUCTION=(opcode[, ... ]) has the same effect as SET BREAK 
/TEMPORARY/INSTRUCTION=(opcode[, . . . ]);GO. 


If you specify a vector instruction, do not include an instruction qualifier 
(/U, /V, /M, /0, or /1) with the instruction mnemonic. 


/AINTO 


If execution is currently suspended at a routine call, STEP/INTO executes 
the program up to the beginning of that routine (steps into that routine). 
Otherwise, STEP/INTO has the same effect as STEP without a qualifier. 
The /INTO qualifier is the opposite of /OVER (the default behavior). 


The STEP/INTO behavior can be modified by also using the /[NO]JSB, 
/[NO]SHARE, and /[NO]JSYSTEM qualifiers. 
/JSB 


/NOJSB 
Qualifies a previous SET STEP INTO command or a current STEP/INTO 
command. 
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If execution is currently suspended at a routine call and the routine is 
called by a JSB instruction, STEP/INTO/NOJSB has the same effect as 
STEP/OVER. Otherwise, STEP/INTO/NOJSB has the same effect as STEP 
/JINTO. 


Use STEP/INTO/JSB to override a previous SET STEP NOJSB command. 
STEP/AINTO/JSB enables a STEP/INTO command to step into routines 
that are called by a JSB instruction, as well as into routines that are 
called by a CALL instruction. 


The /JSB qualifier is the default for all languages except DIBOL. The 
/NOJSB qualifier is the default for DIBOL. In DIBOL, application-declared 
routines are called by the CALL instruction and DIBOL run-time library 
routines are called by the JSB instruction. 


/LINE 


Executes the program to the next line of source code. However, note that 
the debugger skips over any source lines that do not result in executable 
code when compiled (for example, comment lines). STEP/LINE has the 
same effect as SET BREAK/TEMPORARY/LINE;GO. This is the default 
behavior for all languages. 


/OVER 


If execution is currently suspended at a routine call, STEP/OVER executes 
the routine up to and including the routine’s RET instruction (steps over 
that routine). The /OVER qualifier is the default behavior and is the 
opposite of /INTO. 


/RETURN 


Executes the routine in which execution is currently suspended up to 

its RET instruction (that is, up to the point just prior to transferring 
control back to the calling routine). This enables you to inspect the 
local environment (for example, obtain the values of local variables) 
before the RET instruction deletes the routine’s call frame from the call 
stack. STEP/RETURN has the same effect as SET BREAK/TEMPORARY 
/RETURN;GO. 


STEP/RETURN n executes the program up n levels of the call stack. 


/SHARE (default) 


/NOSHARE 
Qualifies a previous SET STEP INTO command or a current STEP/INTO 
command. 


If execution is currently suspended at a call to a shareable image routine, 
STEP/INTO/NOSHARE has the same effect as STEP/OVER. Otherwise, 
STEP/INTO/NOSHARE has the same effect as STEP/ANTO. 


Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE 
command. STEP/INTO/SHARE enables a STEP/INTO command to step 
into shareable image routines, as well as into other kinds of routines. 


/SILENT | 
/NOSILENT (default) 


Controls whether the "stepped to ... " message and the source line 
for the current location are displayed after the STEP has completed. 
The /NOSILENT qualifier specifies that the message is displayed. The 


STEP 


/SILENT qualifier specifies that the message and source line are not 
displayed. The /SILENT qualifier overrides /SOURCE. 


/SOURCE (default) 
/NOSOURCE 


Controls whether the source line for the current location is displayed after 
the STEP has completed. The /SOURCE qualifier specifies that the source 
line is displayed. The /NOSOURCE qualifier specifies that the source line 
is not displayed. The /SILENT qualifier overrides /SOURCE. See also SET 
STEP [NOJSOURCE. 


/SYSTEM (default) 


/NOSYSTEM 


/LNOJSYSTEM qualifies a previous SET STEP INTO command or a current 
STEP/INTO command. 


If execution is currently suspended at a call to a system routine (in P1 
space), STEP/INTO/NOSYSTEM has the same effect as STEP/OVER. 
Otherwise, STEP/INTO/NOSYSTEM has the same effect as STEP/INTO. 


Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM 
command. STEP/INTO/SYSTEM enables a STEP/INTO command to step 
into system routines, as well as into other kinds of routines. 


/VECTOR_INSTRUCTION 
Note: This qualifier applies to vectorized programs. 


Executes the program to the next vector instruction. STEP/VECTOR_ 
INSTRUCTION has the same effect as SET BREAK/TEMPORARY 
/VECTOR_INSTRUCTION;GO. 





DESCRIPTION 


The STEP command is one of the four debugger commands that can be 
used to execute your program (the others are CALL, EXIT, and GO). 


The behavior of the STEP command depends on the following factors: 


e The default STEP mode previously established with a SET STEP 
command, if any. 


¢ The qualifier specified with the STEP command, if any. 


e The number of step units specified as parameter to the STEP 
command, if any. 


If no SET STEP command was previously entered, the debugger takes 
the following default action when you enter a STEP command without 
specifying a qualifier or parameter: 


1 Executes a line of source code (STEP/LINE is the default). 


2 Reports that execution has completed by issuing a "stepped to... " 
message (STEP/NOSILENT is the default). 


3 Displays the line of source code at which execution is suspended (STEP 
/SOURCE is the default). 


4 Issues the prompt. 
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The following STEP command qualifiers affect the location to which you 
step: 


/EXCEPTION 
AINSTRUCTION[=(opcode[, ... ])] 
/LINE 

/RETURN 
/VECTOR_INSTRUCTION 


The following qualifiers affect what output is seen upon completion of a 
step: 


/[NOJSILENT 
/[(NO]SOURCE 


The following qualifiers affect what happens at a routine call: 


INTO 
[NO|JSB 
/OVER 
/[NO]SHARE 
/[NO|ISYSTEM 


If you plan to enter several STEP commands with the same qualifiers, you 
can first use the SET STEP command to establish new default qualifiers 
(for example, SET STEP INTO NOSYSTEM makes the STEP command 
behave like STEP/INTO/NOSYSTEM). Then you do not have to use those 
qualifiers with the STEP command. You can override the current default 
qualifiers for the duration of a single STEP command by specifying other 
qualifiers. Use the SHOW STEP command to identify the current STEP 
defaults. 


If an exception breakpoint is triggered (resulting from a SET BREAK 
/EXCEPTION or a STEP/EXCEPTION command), execution is suspended 
before any application-declared condition handler is invoked. If you then 
resume execution with the STEP command, the debugger resignals the 
exception and the program executes to the beginning of (steps into) the 
condition handler, if any. 


If you are using the multiprocess debugging configuration to debug a 
multiprocess program (if the logical name DBG$PROCESS has the value 
MULTIPROCESS), note the following additional points: 


¢ The STEP command is executed in the context of the visible process, 
but images in any other processes that are not on hold (through a SET 
PROCESS/HOLD command) are also allowed to execute. If you use the 
DO command to broadcast a STEP command to one or more processes, 
the STEP command is executed in the context of each specified process 
that is not on hold, but images in any other processes that are not on 
hold are also allowed to execute. In all cases, a hold condition in the 
visible process is ignored. 


STEP 


e After execution is. started, the way in which it continues depends on 
whether the command SET MODE [NOJINTERRUPT was entered. 
By default (SET MODE INTERRUPT), execution continues until it 
is suspended in any process. At that point, execution is interrupted 
in any other processes that were executing images, and the debugger 
prompts for input. 


Related commands: (SET, SHOW) STEP, GO, SET BREAK/EXCEPTION, 
CALL, EXIT, DO, SET PROCESS, SET MODE [NOJINTERRUPT. 





EXAMPLES 


DBG> SHOW STEP 
step type: source, nosilent, by line, 
over routine calls 
DBG> STEP 
stepped to SQUARESSMAIN\SLINE 4 
4; OPEN (UNIT=8, FILE=’DATAFILE.DAT’, STATUS=’ OLD’ ) 
DBG> 


The SHOW STEP command identifies the default qualifiers currently in 
effect for the STEP command. In this case, the STEP command, without 
any parameters or qualifiers, causes the debugger to execute the next 
line of source code. After the STEP command has completed, execution is 
suspended at the beginning of line 4. 


DBG> STEP 5 

stepped to MAIN\SLINE 47 
47% SWAP (X,Y); 

DBG> 


This command causes the debugger to execute the next 5 lines of source 
code. After the STEP command has completed, execution is suspended at 
the beginning of line 47. 


DBG> STEP/INTO . 
stepped to routine SWAP 
23: procedure SWAP (A,B: in out integer) is 


DBG> STEP 
stepped to MAIN\SWAP\SLINE 24 
24; TEMP: integer := 0; 


DBG> STEP/RETURN 

stepped on return from MAIN\SWAP\SLINE 24 to MAIN\SWAP\%SLINE 29 
29: end SWAP; 

DBG> 


In this example, the STEP/INTO command causes the debugger to execute 
the program up to the beginning of the routine that is being called at 

the current PC value (routine SWAP, in this case). The STEP command 
executes the next line of source code. The STEP/RETURN command 
causes the debugger to finish executing routine SWAP up to its RET 
instruction (that is, up to the point just prior to transferring control back 
to the calling routine). 
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4 DBG> SET STEP INSTRUCTION 
DBG> SHOW STEP 


step type: source, nosilent, by instruction, 
over routine calls 
DBG> STEP 


stepped to SUBIL\%SLINE 26: MOVL S*#4,B*-20 (FP) 
26% Z:integer:=4; 
DBG> 


In this example, the SET STEP INSTRUCTION command establishes the 
default STEP command qualifier to be INSTRUCTION. This is verified 

by the SHOW STEP command. The STEP command causes the debugger 
to execute the next instruction. After the STEP command has completed, 


execution is suspended at the first instruction (MOVL) of line 26 in module 
SUB1. 
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SYMBOLIZE 


Converts a memory address to a symbolic representation, if possible. 





FORMAT 


SYMBOLIZE address-expression[, ... ] 





PARAMETERS address-expression 


Specifies an address expression to be symbolized. Do not use the asterisk 
wildcard character (* ). 





DESCRIPTION 


If the address is a static address, it is symbolized as the nearest preceding 
symbol name, plus an offset. If the address is also a code address and 

a line number can be found that covers the address, the line number is 
included in the symbolization. 


If the address is a register address, the debugger displays all symbols in 
all set modules that are bound to that register. The full path name of each 
such symbol is displayed. The register name itself ("%R5", for example) is 
also displayed. 


If the address is a call stack location in the call frame of a routine in a 
set module, the debugger searches for all symbols in that routine whose 
addresses are relative to the Frame Pointer (FP) or the Stack Pointer 
(SP). The closest preceding symbol name plus an offset is displayed as the 
symbolization of the address. A symbol whose address specification is too 
complex is ignored. 


If the debugger can find no symbolization for the address, a message is 
displayed. 


Related commands: SET MODE [NO]JSYMBOLIC, SET MODE [NO]LINE, 
SHOW SYMBOL, (SET, SHOW, CANCEL) MODULE, EVALUATE 
/ADDRESS. 





EXAMPLES 


DBG> SYMBOLIZE 


RS 


address PROG\SR5: 


PROG\X 
DBG> 


This example shows that the local variable X in routine PROG is located 
in register R5. 
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AB  DBG> SYMBOLIZE %HEX 27C9E3 
address 0027C9E3: 
MOD5\X 
DBG> 


This command directs the debugger to treat the integer literal 27C9EK3 as a 
hexadecimal value and convert that address to a symbolic representation, 
if possible. The address converts to the symbol X in module MOD5. 
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SYNCHRONIZE VECTOR MODE 


Note: This command applies to vectorized programs. 
Forces immediate synchronization between the scalar and vector processors. 





FORMAT SYNCHRONIZE VECTOR_MODE 





DESCRIPTION The command SYNCHRONIZE VECTOR_MODE forces immediate 
synchronization between the scalar and vector processors by issuing a 
SYNC and an MSYNC instruction. The effect is as follows: 


e Any exception that was caused by a vector instruction and was still 
pending delivery is immediately delivered. Note that forcing the 
delivery of a pending exception triggers an exception breakpoint or 
tracepoint (if one was set) or invokes an exception handler (if one is 
available at that location in the program). 


e Any read or write operation between vector registers and either the 
general registers or memory is completed immediately—that is, any 
vector memory instruction that was still being executed completes 
execution. 


Entering the command SYNCHRONIZE VECTOR_MODE is equivalent to 
issuing SYNC and MSYNC instructions at the location in the program at 
which execution is suspended. 


By default, the debugger does not force synchronization between the 
scalar and vector processors during program execution (SET VECTOR_ 
MODE NOSYNCHRONIZED). Use the command SET VECTOR_MODE 
SYNCHRONIZED to force such synchronization. 


Related commands: SET VECTOR_MODE [NO]JSYNCHRONIZED, SHOW 
VECTOR_MODE. 





EXAMPLES 


DBG> SYNCHRONIZE VECTOR MODE 
*DEBUG-I-SYNCREPCOM, Synchronize reporting complete 
DBG> 


The SYNCHRONIZE VECTOR _ MODE command forces immediate 
synchronization between the scalar and vector processors. In this example, 
the diagnostic message indicates that the synchronization operation has 
completed and that all pending vector exceptions have been delivered and 
reported. 
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DBG> STEP @ 

stepped to .MAIN.\SUB\%SLINE 99 
99: VVDIVD v1,V0,vV2 

DBG> sTEP @ 

stepped to .MAIN.\SUB\SLINE 100 


100: CLRL RO 
DBG> EXAMINE/FLOAT %V2 
O\SV2 
[OJ]: 13.53400 
[1]: Reserved operand, encoded as floating divide by zero 


[2]: 247.2450 


DBG> SYNCHRONIZE VECTOR MODE @ 
SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%SLINE 100 
100: CLRL RO 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ This STEP command suspends program execution on line 99, just 
before a VVDIVD instruction is executed. Assume that, in this 
example, the instruction will trigger a floating-point divide-by-zero 
exception. 


@ This STEP command executes the VVDIVD instruction. Note, 


however, that the exception is not delivered at this point in the 
execution of the program. 


© The EXAMINE/FLOAT command displays a decoded exception 
message in element 1 of the destination register, V2. This confirms 
that a floating-point divide-by-zero exception was triggered and is 
pending delivery. 


@ The SYNCHRONIZE VECTOR_MODE command forces the immediate 
delivery of the pending vector exception. 
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TYPE 


Displays lines of source code. 





FORMAT 


TYPE /[[mod-name\jline-numf[-line-num] 
[,[mod-name\fline-num[-line-num][, ... |] 





PARAMETERS 


mod-name 

Specifies the module that contains the source lines to be displayed. If you 
specify a module name along with the line numbers, use standard path 
name notation: insert a backslash (\ ) between the module name and the 
line numbers. 


If you do not specify a module name, the debugger uses the current scope 
(as established by a previous SET SCOPE command, or the PC scope if 
no SET SCOPE command was entered) to find source lines for display. 
If you specify a scope search list with the SET SCOPE command, the 
debugger searches for source lines only in the module associated with the 
first named scope. 


line-num 
Specifies a compiler-generated line number (a number used to label a 
source language statement or statements). 


If you specify a single line number, the debugger displays the source code 
corresponding to that line number. 


If you specify a list of line numbers, separating each with a comma, 
the debugger displays the source code corresponding to each of the line 
numbers. 


If you specify a range of line numbers, separating the beginning and 
ending line numbers in the range with a colon, the debugger displays the 
source code corresponding to that range of line numbers. 


You can display all the source lines of a module by specifying a range of 
line numbers starting from 1 and ending at a number equal to or greater 
than the largest line number in the module. 


After displaying a single line of source code, you can display the next line 
of that module by entering a TYPE command without a line number— 
that is, by entering a TYPE command and then pressing the Return key. 
You can then display the next line and successive lines by repeating this 
sequence, in effect, reading through your source program one line at a 
time. 





DESCRIPTION 


The TYPE command displays the lines of source code that correspond to 
the specified line numbers. The line numbers used by the debugger to 
identify lines of source code are generated by the compiler. They appear in 
a compiler-generated listing and in a screen-mode source display. 
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If you specify a module name with the TYPE command, the module 
must be set. Use the SHOW MODULE command to determine whether 
a particular module is set. Then use the SET MODULE command, if 
necessary. 


In screen mode, the output of a TYPE command is directed at the current 
source display, not at an output or DO display. The source display shows 
the lines specified and any surrounding lines that fit in the display 
window. 


Related commands: SET MODE [NO]JSCREEN, EXAMINE/SOURCE, 
SET STEP [NO]JSOURCE, STEP/[NO]JSOURCE, SET (BREAK, TRACE, 
WATCH) /[NOJSOURCEH, (SET, SHOW, CANCEL) SCOPE. 





EXAMPLES 


DBG> TYPE 160 
module COBOLTEST 
160: START~-IT-PARA. 
DBG> TYPE 
module COBOLTEST 
161: MOVE SCi1 TO ESO. 
DBG> 


In this example, the first TYPE command displays line 160, using the 
current scope to locate the module containing that line number. The 
second TYPE command, entered without specifying a line number, displays 
the next line in that module. 


DBG> TYPE 160:163 
module COBOLTEST 
160: START-IT-PARA. 


161: MOVE SCl TO ESO. 

162: DISPLAY ESO. 

163: MOVE SCl TO ES1. 
DBG> 


This command displays lines 160 to 163, using the current scope to locate 
the module. 


DBG> TYPE SCREEN IO\7,22:24 


This command displays line 7 and lines 22 to 24 in module SCREEN_IO. 
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WHILE 


Executes a sequence of commands while the language expression (Boolean 
expression) you have specified evaluates as true. 





FORMAT WHILE Boolean-expression DO (command; ... ]) 





PARAMETERS’ Boolean-expression 


Specifies a language expression that evaluates as a Boolean value (true or 
false) in the currently set language. 


command 


Specifies a debugger command. If you specify more than one command, 
separate them with semicolons. 





DESCRIPTION The WHILE command evaluates a Boolean expression in the current 
anguage. If the value is true, the command list in the DO clause is 
executed. The command then repeats the sequence, reevaluating the 
Boolean-expression and executing the command-list until the expression is 
evaluated as false. 


If the Boolean-expression is false, the WHILE command terminates. 
Related commands: FOR, REPEAT, EXITLOOP. 





EXAMPLE 


DBG> WHILE (X .EQ. 0) DO (STEP/SILENT) 


This command directs the debugger to keep stepping through the program 
until X no longer equals 0 (FORTRAN example). 
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Command Defaults 


This appendix identifies the defaults associated with debugger commands. 


Command 


@iile-spec 


CALL 
CONNECT 
DEFINE 
DEFINE/KEY 


DELETE/KEY 
DEPOSIT 


DISPLAY 


DO 
EDIT 


ENABLE (DISABLE) AST 
EVALUATE 


Default 


For any field of the file specification that is not 
specified, the default is SYS$DISK:[]DEBUG.COM. To 
change the default, use the SET ATSIGN command. 


Arguments are passed by address (%ADDR). CALL 
/AST/NOSAVE_VECTOR_STATE. 


If no process is specified, the CONNECT command 
brings any processes that are waiting to connect to 
the debugging session under debugger control. 


DEFINE/ADDRESS 


DEFINE/KEY/ECHO/NOIF_STATE/NOLOCK_STATE 
/LOG/NOSET_STATE/NOTERMINATE 


DELETE/KEY/LOG/NOSTATE 


Language expressions are interpreted according to 
the currently set language. Address expressions 
that are associated with compiler generated types 
are treated according to that type. Other address 
expressions are treated as having the type longword 
integer. 


DISPLAY/DYNAMIC/NOMARK_CHANGE/POP when 
applied to an existing display. The current display 
kind, window, and size remain unchanged. 


DISPLAY/DYNAMIC/POP/SIZE:64 when creating 

a display. The default window is either H1 or H2, 
alternating between these two with each newly 
created display. The default display kind is "output". 


DO/PROCESS=* 


EDIT/NOEXIT. The default is to invoke the VAX 
Language-Sensitive Editor in a spawned subprocess. 
This can be changed with a SET EDITOR command. 
The default source file to be edited is the file whose 
source code appears in the current source display. 
The default position of the editing cursor is either the 
beginning of the line that is centered in the current 
source display, or the beginning of line 1 if the editor 
was set to /NOSTART_POSITION. 


ENABLE AST 


Language expressions are interpreted according to 
the currently set language. 


Command Defaults 
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Command 


EXAMINE 


EXPAND 


EXTRACT 


MOVE 
SCROLL 


SEARCH 


SELECT 
SET ATSIGN 
SET BREAK 


SET DEFINE 
SET EDITOR 
SET IMAGE 

SET KEY 

SET LANGUAGE 


SET LOG 

SET MARGINS 

SET MAX_SOURCE_FILES 
SET MODE 

SET OUTPUT 


SET PROCESS 


Default 


The contents of program locations that are associated 
with a compiler generated type are interpreted and 
displayed according to that type. The contents of 
other locations are interpreted and displayed as 
longword integers. 


EXPAND/DOWN, /UP: 1 line. EXPAND/LEFT, RIGHT: 
1 column. 


If you specify /SCREEN_LAYOUT, the 
default specification for the output file is 
SYS$DISK:[JDBGSCREEN.COM. Otherwise, 
the default specification for the output file is 
SYSS$DISK:[ DEBUG. TXT. 


MOVE/DOWN, /UP: 1 line. MOVE/LEFT, RIGHT: 1 
column. 


SCROLL/DOWN, /UP: 3/4 of window height. SCROLL 
/LEFT, /RIGHT: 8 columns. 


SEARCH/NEXT/STRING. If no module name is 
specified, the debugger uses the current scope to find 
a module and searches that module for an occurrence 
of the string. The current scope is that established by 
a previous SET SCOPE command, or the PC scope 
if no SET SCOPE command was entered. Also, if 

no string is specified, the string specified in the last 
SEARCH command, if any, is used. 


SELECT/SCROLL 
SET ATSIGN SYS$DISK:[]DEBUG.COM 


SET BREAK/INTO/JSB/SHARE/SYSTEM 
/NOSILENT/SOURCE 


SET DEFINE ADDRESS 

SET EDITOR/NOSTART_POSITION 
The current image is the main image. 
SET KEY/STATE=DEFAULT _ 


The default language is the language of the module 
that contains the image transfer address (main 
program). 

SET LOG SYS$DISK:[]DEBUG.LOG 


SET MARGINS 1:255 (left margin: 1, right margin: 
255) | 


SET MAX_SOURCE_FILES 5 


SET MODE DYNAMIC, NOG_FLOAT, KEYPAD, 
LINE, NOOPERANDS, NOSCREEN, NOSEPARATE, 
SCROLL, SYMBOLIC 


SET OUTPUT NOLOG, NOSCREEN_LOG, » 
TERMINAL, NOVERIFY 


SET PROCESS/VISIBLE 


Command 


SET PROMPT 


SET RADIX 


SET SCOPE 


SET SEARCH 
SET SOURCE 


SET STEP 
SET TERMINAL 
SET TRACE 


SET TYPE 


SET VECTOR_MODE 
SET WATCH 


SPAWN 
STEP 
TYPE 


Command Defaults 


Default 


SET PROMPT/NOPOP "DBG> ". 

For multiprocess programs: | 
SET PROMPT/NOPOP/SUFFIX=PROCESS _ 
NUMBER "DBG_" 


For all languages except BLISS and MACRO: SET 
RADIX DECIMAL. For BLISS and MACRO: SET 
RADIX HEXADECIMAL. 


The debugger looks up a symbol specified without a 
path name prefix according to the scope search list 
0,1, ...,N (where N is the number of calls in the 
call stack). If the symbol is not found, the debugger 
searches the run-time symbol table, then the global 
symbol table if necessary. 


SET SEARCH NEXT, STRING 


When searching for a source file, the debugger uses 
the full file specification that is stored in the run-time 
symbol table (RST). 


SET STEP SOURCE, NOSILENT, OVER, LINE 


The values of /PAGE and /WIDTH default to those set 
at DCL level (see the VMS DCL Dictionary or enter 
the DCL command HELP SET TERMINAL). 


SET TRACE/INTO/JSB/SHARE/SYSTEM /NOSILENT 
/SOURCE 


The default type for program locations that are 
associated with a compiler generated type is that 
type. The default type for other locations is longword 
integer. 


SET VECTOR_MODE NOSYNCHRONIZED 


For static variables: SET WATCH/NOSILENT 
/SOURCE. For nonstatic variables: SET WATCH 
/NOSILENT/OVER/SOURCE. 


SPAWN/WAIT 
STEP/OVER/LINE 


lf no module name is specified, the debugger uses 
the current scope to find a module and searches 
that module for source lines for display. The current 
scope is that established by a previous SET SCOPE 
command, or the PC scope if no SET SCOPE 
command was entered. Also, if no line is specified 
after a single source line has been displayed with 
the TYPE command, the next line in that module is 
displayed by default. 
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5 Predefined Key Functions 


When you invoke the debugger, certain predefined functions (commands, 
sequences of commands, and command terminators) are assigned to keys 
on the numeric keypad, to the right of the main keyboard. By using these 
keys you can enter certain commands with fewer keystrokes than if you 
were to type them at the keyboard. For example, pressing the COMMA (, ) 
keypad key is equivalent to typing GO and then pressing the Return key. 
Terminals and workstations that have an LK201 keyboard have additional 
programmable keys compared to those on VT100 keyboards (for example, 
“Help” or “Remove”), and some of these keys are also assigned debugger 
functions. 


To use function keys, keypad mode must be enabled (SET MODE 
KEYPAD). Keypad mode is enabled when you invoke the debugger. If 
you do not want keypad mode enabled, perhaps because the program 
being debugged uses the keypad for itself, you can disable keypad mode by 
entering the SET MODE NOKEYPAD command. 


The keypad key functions that are predefined when you invoke the 
debugger are identified in summary form in Figure B-1. Table B-1, 
Table B-2, Table B—3, and Table B—4 identify all key definitions in detail. 
Most keys are used for manipulating screen displays in screen mode. To 
use screen mode commands, you must first enable screen mode by pressing 
keypad key PF3 (SET MODE SCREEN). In screen mode, to re-create 

the default layout of various windows, press the keypad-key sequence 
BLUE-MINUS (PF4 followed by the MINUS key (—)). 


To use the keypad keys to enter numbers rather than debugger commands, 
enter the command SET MODE NOKEYPAD. 


B.1 DEFAULT, GOLD, BLUE Functions 


A given key typically has three predefined functions: 


¢ One function is entered by pressing the given key by itself. This is the 
DEFAULT function. | 


¢ A second function is entered by pressing and releasing the PF1 key 
and then pressing the given key. This is the GOLD function, because 
PF 1 is also called the GOLD key. 


e A third function is entered by pressing and releasing the PF4 key and 
then pressing the given key. This is the BLUE function, because PF4 
is also called the BLUE key. 


Predefined Key Functions 
B.1 DEFAULT, GOLD, BLUE Functions 


Figure B—1 Keypad Key Functions Predefined by the Debugger—Command Interface 
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DISP SRC,INST,OUT SCROLL/UP DISPLAY next DISP next at FS 
DISP INST,REG,OUT SCROLL/TOP SET PROC next 
DISP 2 SRC, 2 INST SCROLL/UP... DISP 2 SRC DISP SRC, OUT 

















SCROLLULEFT 
SCROLL/LEFT:255 
SCROLULEFT... 


EX/SOU .O\%PC 
SHOW CALLS 
SHOW CALLS 3 


SCROLURIGHT 
SCROLURIGHT:255 
SCROLL/RIGHT... 


GO 
SEL/SOURCE next 
SEL/INST next 


ENTER 





EXAMINE 
EXAM(“(prev) 
DISP 3 SRC, 3 INST 


SCROLL/DOWN 
SCROLL/BOTTOM 
SCROLL/DOWN... 


SEL SCROLL next 
SEL OUTPUT next 
DISP 3 SRC 


ENTER 


STEP 
STEPANTO 
STEP/OVER 


LK201 Keyboard: 


Press Keys 2,4,6,8 
F17 SCROLL 
F18 MOVE 

F19 EXPAND 
F20 CONTRACT 

VT-100 Keyboard: 

ope Keys 2,4,6,8 
SET KEY/STATE=DEFAULT SCROLL 
SET KEY/STATE=MOVE MOVE 

SET KEY/STATE=EXPAND EXPAND 
SET KEY/STATE=CONTRACT CONTRACT 
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EXPAND/DOWN 
EXPAND/DOWN:999 
EXPAND/DOWN:5 





EXPAND/UP:~-1 
EXPAND/UP:-999 
EXPAND/UP:-5 


"CONTRACT" 








EXPAND/LEFT:-1 
EXPAND/LEFT:-999 
EXPAND/LEFT:-10 


EXPAND/RIGHT:-1 
EXPAND/RIGHT:-999) 
EXPAND/RIGHT:-10 










EXPAND/DOWN:~1 
EXPAND/DOWN:-999 
EXPAND/DOWN:-5 
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Predefined Key Functions 
B.1 DEFAULT, GOLD, BLUE Functions 


In Figure B—1, the DEFAULT, GOLD, and BLUE functions are listed 
within each key’s outline, from top to bottom respectively. For example, 
pressing keypad key 0 enters the command STEP (DEFAULT function); 
pressing key PF1 and then key 0 enters the command STEP/INTO (GOLD 
function); pressing key PF4 and then key 0 enters the command STEP 
/OVER (BLUE function). 


All command sequences assigned to keypad keys are terminated (executed 
immediately) except for the BLUE functions of keys 2, 4, 6, and 8. These 
unterminated commands are symbolized with a trailing ellipsis ( ... ) 

in Figure B-1. To terminate the command, supply a parameter and then 
press RETURN. For example, to scroll down 12 lines, do the following: 


1 Press key PF4 

2 Press keypad key 2 

3 Type :12 at the keyboard 
4 Press the Return key 


Key Definitions Specific to LK201 Keyboards 


Table B-1 lists keys that are specific to LK201 keyboards and do not 
appear on VT100 keyboards. For each key, the table identifies the 
equivalent command and, for some keys, an equivalent keypad key that 
you can use if you do not have an LK201 keyboard. 


Table B—1 Key Definitions Specific to LK201 Keyboards 


Equivalent 

LK201 Key Command Sequence Invoked Keypad Key 
Fi7 SET KEY/STATE=DEFAULT None 

F1i8 SET KEY/STATE=MOVE None 

F19 SET KEY/STATE=EXPAND None 

F20 SET KEY/STATE=CONTRACT None 

Help HELP KEYPAD SUMMARY None 

Next Screen SCROLL/DOWN 2 

Prev Screen SCROLL/UP 8 

Remove DISPLAY/REMOVE %CURSCROLL None 
Select SELECT/SCROLL %NEXTSCROLL _ 3 


Keys that Scroll, Move, Expand, Contract Displays 


By default, keypad keys 2, 4, 6, and 8 scroll the current scrolling display. 
Each key controls a direction (down, left, right, and up, respectively). By 
pressing keys F18, F19, or F20, you can place the keypad in the MOVE, 
EXPAND, or CONTRACT states. When the keypad is in the MOVE state, 
keys 2, 4, 6, and 8 can be used to move the current scrolling display down, 
left, and so on. Similarly, in the EXPAND and CONTRACT states, the 
four keys can be used to expand or contract the current scrolling display. 
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B.3 Keys that Scroll, Move, Expand, Contract Displays 


B—4 


(See Figure B—1 and Table B-2. Alternative key definitions for VT100 
keyboards are described later in this section.) 


To scroll, move, expand, or contract a display, proceed as follows: 


1 Press key 3 repeatedly, as needed, to select the current scrolling 
display from the display list. 

2 Press key F17, F18, F19, or F20 to put the keypad in the DEFAULT 
(scroll), MOVE, EXPAND, or CONTRACT state, respectively. 


3 Press keys 2, 4, 6, and 8 to perform the desired function. Use the PF1 
(GOLD) and PF4 (BLUE) keys to control the amount of scrolling or 
movement. 


Table B~2 Keys that Change the Key State 


Key Description 

PF1 Invokes the GOLD function of the next key you press. 

PF4 Invokes the BLUE function of the next key you press. 

F17 Puts the keypad in the DEFAULT state, enabling the scroll-display functions 


of keys 2, 4, 6, and 8. The keypad is in the DEFAULT state when you 
invoke the debugger. 


F18 Puts the keypad in the MOVE state, enabling the move-display functions of 
keys 2, 4, 6, and 8. 

F19 Puts the keypad in the EXPAND state, enabling the expand-display 
functions of keys 2, 4, 6, and 8. 

F20 Puts the keypad in the CONTRACT state, enabling the contract-display 


functions of keys 2, 4, 6, and 8. 


If you have a VT100 keyboard, you can simulate the effect of LK201 keys 
F17 to F20 by defining the key sequences GOLD-KP9 and BLUE-KP9 
(currently undefined) as shown below. With these definitions, pressing 
GOLD-KP9 puts the keypad in the DEFAULT (scroll) state; pressing 
BLUE-KP9 cycles the keypad through the DEFAULT, MOVE, EXPAND, 
and CONTRACT states (like cycling through keys F17 to F20). You might 
want to store these key definitions in a command procedure, such as your 
debugger initialization file. 


DEFINE/KEY/IF STATE=(GOLD,MOVE GOLD,EXPAND GOLD, CONTRACT GOLD) - 

/TERMINATE KP9 "SET KEY/STATE=DEFAULT/NOLOG" 
DEFINE/KEY/IF_STATE= (BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=MOVE/NOLOG" 
DEFINE/KEY/IF_ STATE=(MOVE_BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=EXPAND/NOLOG" 
DEFINE/KEY/IF_STATE= (EXPAND BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=CONTRACT/NOLOG" 
DEFINE/KEY/IF_STATE= (CONTRACT BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=DEFAULT/NOLOG" 
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Online Keypad Key Diagrams 


Online HELP for the keypad keys is available by pressing the Help key 
and also the PF2 key, either by itself or with other keys (see Table B-3). 
You can also use the SHOW KEY command to identify key definitions. 
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B.4 Online Keypad Key Diagrams 


Table B—3_ Keys that Invoke Online Help to Display Keypad Diagrams 


Key or 
Key Sequence 


Help 

PF2 

PF1-PF2 
PF4-PF2 
F18-PF2 
F18-PF1-PF2 
F18-PF4-PF2 
F19-PF2 
F19-PF1-PF2 
F19-PF4-PF2 
F20-PF2 
F20-PF1-PF2 


F20-PF4-PF2 


Command Sequence Invoked 


HELP KEYPAD SUMMARY 
HELP KEYPAD DEFAULT 

HELP KEYPAD GOLD 

HELP KEYPAD BLUE 

HELP KEYPAD MOVE 

HELP KEYPAD MOVE_GOLD 
HELP KEYPAD MOVE_BLUE 
HELP KEYPAD EXPAND 

HELP KEYPAD EXPAND_GOLD 
HELP KEYPAD EXPAND_BLUE 
HELP KEYPAD CONTRACT 
HELP KEYPAD CONTRACT_GOLD 


HELP KEYPAD CONTRACT_BLUE 


Description 
Shows a diagram of the keypad keys and 
summarizes each key’s function 


Shows a diagram of the keypad keys and their 
DEFAULT functions 


Shows a diagram of the keypad keys and their 
GOLD functions 


Shows a diagram of the keypad keys and their 
BLUE functions 


Shows a diagram of the keypad keys and their 
MOVE DEFAULT functions 


Shows a diagram of the keypad keys and their 
MOVE GOLD functions 


Shows a diagram of the keypad keys and their 
MOVE BLUE functions 


Shows a diagram of the keypad keys and their 
EXPAND DEFAULT functions 


Shows a diagram of the keypad keys and their 
EXPAND GOLD functions 


Shows a diagram of the keypad keys and their 
EXPAND BLUE functions | 


Shows a diagram of the keypad keys and their 
CONTRACT DEFAULT functions 


Shows a diagram of the keypad keys and their 
CONTRACT GOLD functions 


Shows a diagram of the keypad keys and their 
CONTRACT BLUE functions 
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Debugger Key Definitions 
Table B—4 identifies all key definitions. 


Table B-4 Debugger Key Definitions 


Key 
0 
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State 


DEFAULT 
GOLD 
BLUE 
DEFAULT 


GOLD 


BLUE 


DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 


Command Invoked or Function 


STEP 
STEP/INTO 


STEP/OVER 


EXAMINE. Examines the logical successor of the 
current entity, if one is defined (the next location). 


EXAMINE “. Enables you to examine the logical 
predecessor of the current entity, if one is defined 
(the previous location). 


Displays three sets of predefined process-specific 
source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at S2 and RS2, 
respectively; source and instruction displays for 
the previous process on the process list at $1 
and RS1, respectively; and source and instruction 
displays for the next process on the process list at 
S3 and RS3, respectively. 


SCROLL/DOWN 
SCROLL/BOTTOM 


SCROLL/DOWN (not terminated). To terminate 
the command, supply the number of lines to be 
scrolled (:n) or a display name. 


MOVE/DOWN 
MOVE/DOWN:999 
MOVE/DOWN:5 
EXPAND/DOWN 
EXPAND/DOWN:999 
EXPAND/DOWN:5 
EXPAND/DOWN:-1 
EXPAND/DOWN:-999 
EXPAND/DOWN:-5 


SELECT/SCROLL “%NEXTSCROLL. Selects as 
the current scrolling display the next display in the 
display list after the current scrolling display. 


SELECT/OUTPUT %NEXTOUTPUT. Selects the 
next output display in the display list as the current 
output display. 


(continued on next page) 
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Table B—4 (Cont.) Debugger Key Definitions 


Key 


State 


BLUE 


BLUE 


DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 
BLUE 
DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 


Command Invoked or Function 


Displays three predefined process-specific source 
displays, SRC_n. These are located at $1, S2, 
and S3, respectively, for the previous, current 
(visible), and next process on the process list. 


SELECT/SOURCE %NEXTSOURCE. Selects the 
next source display in the display list as the current 
source display. 


SCROLL/LEFT 
SCROLL/LEFT:255 


SCROLL/LEFT (not terminated). To terminate 
the command, supply the number of lines to be 
scrolled (:n) or a display name. 


MOVE/LEFT 
MOVE/LEFT:999 
MOVE/LEFT:10 
EXPAND/LEFT 
EXPAND/LEFT:999 
EXPAND/LEFT:10 
EXPAND/LEFT:-1 
EXPAND/LEFT:-999 
EXPAND/LEFT:-10 


EXAM/SOURCE .%SOURCE_SCOPE\%PC; 
EXAM/INST .%INST_SCOPE\%PC. In line 
(noscreen) mode, displays the the source line 
and the instruction to be executed next. In screen 
mode, centers the current source display on the 
next source line to be executed, and the current 
instruction display on the next instruction to be 
executed. 


SHOW CALLS 
SHOW CALLS 3 
SCROLL/RIGHT 
SCROLL/RIGHT:255 


SCROLL/RIGHT (not terminated). To terminate 
the command, supply the number of lines to be 
scrolled (:n) or a display name. 


MOVE/RIGHT 
MOVE/RIGHT:999 
MOVE/RIGHT:10 
EXPAND/RIGHT 


(continued on next page) 
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Table B—4 (Cont.) Debugger Key Definitions 


Key 


State 


EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 


BLUE 


DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT _BLUE 
DEFAULT 


Command Invoked or Function 


EXPAND/RIGHT:999 
EXPAND/RIGHT:10 
EXPAND/RIGHT:-1 
EXPAND/RIGHT:-999 
EXPAND/RIGHT:-10 


DISPLAY SRC AT LH1, INST AT RH1, OUT 
AT S45, PROMPT AT S6; SELECT/SCROLL 
/SOURCE SRC; SELECT/INST INST; SELECT 
/OUT OUT. Displays the SRC, INST, OUT, and 
PROMPT displays with the proper attributes. 


DISPLAY INST AT LH1, REG AT RH1, OUT AT 
$45, PROMPT AT S6; SELECT/SCROLL/INST 
INST; SELECT/OUT OUT. Displays the INST, 
REG, OUT, and PROMPT displays with the proper 
attributes. 


Displays two sets of predefined process-specific 
source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at Q1 and RQ1, 
respectively, and source and instruction displays 
for the next process on the process list at Q2 and 
RQ2, respectively. 


SCROLL/UP 
SCROLL/TOP 


SCROLL/UP (not terminated). To terminate the 
command, supply the number of lines to be 
scrolled (:n) or a display name. 


MOVE/UP 
MOVE/UP:999 
MOVE/UP:5 
EXPAND/UP 
EXPAND/UP:999 
EXPAND/UP:5 
EXPAND/UP:-1 
EXPAND/UP:-999 
EXPAND/UP:-5 


DISPLAY %NEXTDISP. Displays the next display in 
the display list through its current window (removed 
displays are not included). 


(continued on next page) 
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Key 


PF1 
PF2 
PF3 


PF4 
COMMA 


MINUS 


ENTER 


PERIOD 


State 


GOLD 


BLUE 


DEFAULT 


GOLD 


BLUE 


DEFAULT 
GOLD 


BLUE 


DEFAULT 


GOLD 
BLUE 


All states 
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Debugger Key Definitions 


Command Invoked or Function 


SET PROCESS/VISIBLE %NEXT_PROCESS. 
Makes the next process in the process list the 
visible process. 


Displays two predefined process-specific source 
displays, SRC_n. These are located at Q1 and 
Q2, respectively, for the visible process and for the 
next process on the process list. 


See Table B-2. 
See Table B-3. 


SET MODE SCREEN; SET STEP NOSOURCE. 
Enables screen mode and suppresses the output 
of source lines that would normally appear in the 
output display (since that output is redundant when 


the source display is present). 


SET MODE NOSCREEN; SET STEP SOURCE. 
Disables screen mode and restores the output of 
source lines. 


DISPLAY/GENERATE. Regenerates the contents 
of all automatically updated displays. 


See Table B—2. 
GO 


SELECT/SOURCE %NEXT_SOURCE. Selects the 
next source display in the display list as the current 
source display. 


SELECT/INSTRUCTION %NEXTINST. Selects the 
next instruction display in the display list as the 
current instruction display. 


DISPLAY %NEXTDISP AT $12345, PROMPT AT 
S6; SELECT/SCROLL %CURDISP. Displays the 
next display in the display list at essentially full 
screen (top of screen to top of PROMPT display). 
Selects that display as the current scrolling display. 


Undefined 

DISPLAY SRC AT H1, OUT AT S45, PROMPT AT 
$6; SELECT/SCROLL/SOURCE SRC; SELECT 
/OUT OUT. Displays the SRC, OUT, and PROMPT 
displays with the proper attributes. This is the 
default display configuration. 


Enables you to enter (terminate) a command. 
Same effect as RETURN. 


Cancels the effect of pressing state keys which do 
not lock the state, such as GOLD and BLUE. Does 
not affect the operation of state keys which lock the 
state, such as MOVE, EXPAND, and CONTRACT. 


(continued on next page) 
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Table B—4 (Cont.) Debugger Key Definitions 


Key 


Next 
Screen 
(E6) 


Prev 
Screen 
(ES) 


Remove 
(E3) 


Select 
(E4) 


Fi7 
Fi8 

F19 

F20 
CTRL/W 
CTRUZ 


State 


DEFAULT 


DEFAULT 


DEFAULT 


DEFAULT 


Command Invoked or Function 


SCROLL/DOWN 


SCROLL/UP 


DISPLAY/REMOVE %CURSCROLL. Removes the 
current scrolling display from the display list. 


SELECT/SCROLL %NEXTSCROLL. Selects as 
the current scrolling display the next display in the 
display list after the current scrolling display. 


See Table B—2. 

See Table B-2. 

See Table B-2. 

See Table B-2. 
DISPLAY/REFRESH 
EXIT 


C 


C.1 





Screen Mode Reference Information 


Display Kinds 


This appendix contains summarized reference information related to 
screen mode. The following topics are covered: 


e Display kinds 

¢ Display attributes 

e Predefined displays 

e Screen-related built-in symbols 


e Screen dimensions and predefined windows 





The DISPLAY command accepts these display-kind keywords and 
parameters: 


DO (command; .. . ]) Specifies an automatically updated output display. 
The commands are executed in the order listed 
each time the debugger gains control. Their output 
forms the contents of the display. If you specify 
more than one command, they must be separated 
by semicolons. 


INSTRUCTION Specifies an instruction display. If selected as 
the current instruction display with the SELECT 
[INSTRUCTION command, it displays the output 
from subsequent EXAMINE/INSTRUCTION 
commands. 


INSTRUCTION (commana) Specifies an automatically updated instruction 
display. The command specified must be an 
EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 


OUTPUT Specifies an output display. If selected as the 
current output display with the SELECT/OUTPUT 
command, it displays any debugger output that is not 
directed to another display. If selected as the current 
input display with the SELECT/INPUT command, it 
echoes debugger input. If selected as the current 
error display with the SELECT/ERROR command, it 
displays debugger diagnostic messages. 


REGISTER Specifies an automatically updated register display. 
The display is updated each time the debugger 
gains conirol. 
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SOURCE 


SOURCE (command) 


Specifies a source display. lf selected as the 
current source display with the SELECT/SOURCE 
command, it displays the output from subsequent 
TYPE or EXAMINE/SOURCE commands. 


Specifies an automatically updated source display. 
The command specified must be a TYPE or 
EXAMINE/SOURCE command. The source display 
is updated each time the debugger gains control. 





C.2 Display Attributes 


The SELECT command assigns an attribute to a display according to the 
qualifier used with that command. The following list identifies each of the 
SELECT command qualifiers, its effect, and the display kinds to which 
you can assign that attribute. 


SELECT 
Qualifier 


/ERROR 


[INPUT 


[INSTRUCTION 


/OUTPUT 


/PROGRAM 


Description 


Selects the specified display as the current error display. Directs 
any subsequent debugger diagnostic message to that display. It 
must be either an output display or the PROMPT display. If no 
display is specified, selects the PROMPT display as the current 
error display. 


Selects the specified display as the current input display. 
Echoes any subsequent debugger input in that display. It 
must be an output display. If no display is specified, unselects 
the current input display: debugger input is not echoed to any 
display. 


Selects the specified display as the current instruction display. 
Directs the output of any subsequent EXAMINE/INSTRUCTION 
command to that display. It must be an instruction display. 
Keypad key sequence BLUE-COMMA selects the next 
instruction display in the display list as the current instruction 
display. If no display is specified, unselects the current 
instruction display: no display has the instruction attribute. 


Selects the specified display as the current output display. 
Directs any subsequent debugger output to that display, except 
where a particular type of output is being directed to another 
display (such as diagnostic messages going to the current error 
display). The specified display must be either an output display 
or the PROMPT display. Keypad key sequence GOLD-3 selects 
the next output display in the display list as the current output 
display. If no display is specified, selects the PROMPT display 
as the current output display. 


Selects the specified display as the current program display. 
Tries to force any subsequent program input or output to that 
display. Currently, only the PROMPT display can be specified. 
If no display is specified, unselects the current program display: 
program output is no longer forced to the PROMPT display. 


SELECT 
Qualifier 


/PROMPT 


/SCROLL 


/SOURCE 
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Description 


Selects the specified display as the current prompt display, 
where the debugger prompts for input. Currently, only the 

_ PROMPT display can be specified. You cannot unselect the 
PROMPT display. 


Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. Key 3 selects 
as the current scrolling display the next display in the display 
list after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the scroll 
attribute. 


Selects the specified display as the current source display. 
Directs the output of any subsequent TYPE or EXAMINE 
/SOURCE command to that display. It must be a source display. 
Keypad key sequence BLUE-3 selects the next source display 
in the display list as the current source display. If no display is 
specified, unselects the current source display: no display has 
the source attribute. 


By default, when you invoke screen mode, the predefined displays are 
selected for attributes as follows: 


Attribute 


Error 
Input 
Instruction 
Output 
Program 
Prompt 
Scroll 
Source 


Predefined Display 


PROMPT 

no display selected 
no display selected 
OUT 

PROMPT 
PROMPT 

SRC 

SRC 





C.3 Predefined Displays 


Properties of the predefined displays SRC, OUT, PROMPT, INST and REG 
are summarized in this section. 
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C.3.1 SRC (Source Display) 


SRC is an automatically updated source display. It shows the source code 
of the module being debugged, if that source code is available. The arrow 
points to the source line corresponding to the current PC value (where 
execution is suspended). 


The default characteristics of the SRC display are the following: 


Display kind source (examine/source .%source_scope\%pc) 
Attributes scroll, source 

Position H1 

Size 64 lines 

Dynamic yes 


%SOURCE_SCOPE is a built-in scope that has the following properties: 


¢ By default ZSOURCE_SCOPE denotes scope 0, which is the scope of 
the routine where execution is currently suspended. 


e Ifyou have reset the scope search list relative to the call stack by 
means of the SET SCOPE/CURRENT command, ZSOURCE_SCOPE 
denotes the current scope specified (the scope of the routine at the 
start of the search list). 


e If source code is not available for the routine in the current scope, 
%SOURCE_SCOPE denotes scope N, where N is the first level down 
the call stack for which source code is available. 


When displaying source lines that are not associated with the module 
where execution is suspended, the debugger issues the following message: 


%DEBUG-I-SOURCESCOPE, Source lines not available for .0\3PC. 
Displaying source ina caller of the current routine. 


C.3.2 OUT (Output Display) 


OUT shows all debugger output that is not directed to another display. 
The default characteristics of the OUT display are the following: 


Display kind output 
Attribute Output 
Position $45 

Size 100 lines 
Dynamic yes 


C.3.3 PROMPT (Prompt Display) 


PROMPT is the display in which the debugger prompts for input and, by 
default, forces program output and prints debugger diagnostic messages. 
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PROMPT has different properties and restrictions than other displays. 
This is to eliminate possible confusion when manipulating that display: 


e ‘You cannot hide, remove, permanently delete, or scroll PROMPT. 


e ‘You can contract PROMPT down to 2 lines. You cannot contract 


PROMPT horizontally. 
The default characteristics of the PROMPT display are the following: 
Display kind program 
Attributes error, prompt, program (no other display can have the prompt or 
program attributes) 
Position S6 
size Not applicable (PROMPT is not scrollable) 
Dynamic yes 


C.3.4 INST (Instruction Display) 


INST is an automatically updated instruction display. It shows the 
instruction stream of the routine being debugged. The instructions 
displayed are decoded from the image being debugged. The arrow points 
to the instruction at the current PC value. 


The default characteristics of the INST display are the following: 


Display kind instruction (examine/instruction .%inst_scope\%pc) 
Attributes none 

Position H1, removed 

Size 64 lines 

Dynamic yes 


%INST_SCOPE is a built-in scope that has the following properties: 


e By default 2INST_SCOPE denotes scope 0, which is the scope of the 
routine where execution is currently suspended. 


e¢ If you have reset the scope search list relative to the call stack by 
means of the SET SCOPE/CURRENT command, ZINST_SCOPE 
denotes the current scope specified (the scope of the routine at the 
start of the search list). 


C.3.5 REG (Register Display) 


REG automatically shows the current values, in hexadecimal format, 

of the VAX general registers (RO to R11, AP, FP, SP, and PC), the four 
condition code bits (C,V, Z, and N) of the processor status longword (PSL), 
and as many of the top call stack values as can be displayed in the window. 


The register values displayed are for the routine in which execution is 
currently suspended. The values are updated whenever the debugger 
takes control. Any changed values are highlighted. 
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The default characteristics of the REG display are the following: 


Display kind register 
Attribute none 

Position RH1, removed 
Size 64 lines 
Dynamic yes 


If the register window is resized, the debugger automatically reformats the 
displayed information to adapt to the new window size. 


Display REG does not display the current values of the VAX vector 
registers. To display data contained in vector registers or vector control 
registers in screen mode, use a DO display. (See Section 7.6.1.) 


C.4 Screen-Related Built-In Symbols 


The following built-in symbols are available for specifying displays and 
screen parameters in language expressions: 


¢ %SOURCE_SCOPE—Used to display source code. ZSOURCE_SCOPE 
is described in Section C.3.1. 


¢ %INST_SCOPE—Used to display instructions. %2INST_SCOPE is 
described in Section C.3.4. 


¢ %PAGE, %7 WIDTH—Used to specify the current screen height and 
width. 


¢ %CURDISP, 2ZCURSCROLL, 2NEXTDISP, 2NEXTINST, 
%NEXTOUTPUT, ZNEXTSCROLL, ZNEXTSOURCE—Used to specify 
displays in the display list. 


C.4.1 Screen Height and Width 


The built-in symbols %PAGE and %WIDTH return, respectively, the 
current height and width of the terminal screen. These symbols can 

be used in various expression, such as for window specifications. For 
example, the following command defines a window named MIDDLE that 
occupies a region around the middle of the screen: 


DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2, SWIDTH/4, SWIDTH/2) 


C.4.2 Display Built-In Symbols 


Each time you refer to a specific display with a DISPLAY command, the 
display list is updated and reordered, if necessary. The most recently 
referenced display is put at the tail of the display list, since that display is 
pasted last on the pasteboard (the display list can be identified by entering 
a SHOW DISPLAY command). 
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You can use display built-in symbols to specify displays relative to their 
positions in the display list. These symbols, listed as follows, enable you 
to refer to displays by their relative positions in the list instead of by their 
explicit names. The symbols are used mainly in keypad key definitions or 
command procedures. 


Display symbols treat the display list as a circular list. Therefore, you can 
enter any commands that use display symbols to cycle through the display 
list until you reach the display you want. 


%CURDISP The current display. This is the display most recently referenced 
with a DISPLAY command—the least occluded display. 

%CURSCROLL The current scrolling display. This is the default display for the 
SCROLL, MOVE, and EXPAND commands, as well as for the 
associated keypad keys (2, 4, 6, and 8). 

%NEXTDISP The next display in the list after the current display. The next 
display is the display that follows the topmost display. Because 
the display list is circular, this is the display at the bottom of the 
pasteboard—the most occluded display. 

%NEXTINST The next instruction display in the display list after the current 
instruction display. The current instruction display is the 
display that receives the output from EXAMINE/INSTRUCTION 
commands. 


%NEXTOUTPUT The next output display in the display list after the current output 
display. An output display receives debugger output that is not 
already directed to another display. 

%NEXTSCROLL _ The next display in the display list after the current scrolling 
display. 

%NEXTSOURCE _ The next source display in the display list after the current source 


display. The current source display is the display which receives 
the output from TYPE and EXAMINE/SOURCE commands. 


C.5 Screen Dimensions and Predefined Windows 


On a VT-series terminal, the screen consists of 24 lines by 80 or 132 
columns. On a workstation, the screen is larger in both height and 
width. The debugger can accommodate screen sizes up to 100 lines by 
255 columns. 


The debugger has many predefined windows that you can use to position 
displays on the screen. The SHOW WINDOW command identifies all 
predefined and user defined windows. The predefined windows are 
expressed in terms of fractions of the screen dimensions (for example, 
quarters, halves, and so on). Therefore, the positions and dimensions 

of the predefined windows that are indicated by the SHOW WINDOW 
command are adjusted for the screen dimensions. 


In addition to the full height and width of the screen, the predefined 
windows include all possible regions that result from dividing the 
screen vertically into halves, thirds, quarters, sixths, and eighths, and 
horizontally into left and right halves. 
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The following conventions apply to the names of predefined windows. The 
prefixes L and R denote left and right windows, respectively. Other letters 
denote the full screen (FS) or fractions of the screen height (H: half, T: 
third, Q: quarter, S: sixth, E: eighth). The trailing numbers denote specific 
fractions of the screen height, starting from the top. For example: 


e Windows T1, T2, and T3 occupy the top, middle and bottom thirds of 
the screen, respectively. 


¢ Window RH2 occupies the right bottom half of the screen. 
e Window LQ23 occupies the left middle two quarters of the screen. 
e¢ Window S45 occupies the fourth and fifth sixths of the screen. 


The horizontal boundaries (start-column, column-count) of the predefined 
windows for the default terminal screen width of 80 columns are as 
follows: 


e Left hand windows: (1,40) 
¢ Right hand windows: (42,39) 


The vertical boundaries (start-line, line-count) of the predefined windows 
for the default terminal screen height of 24 lines are as follows: 


Window Name Start-line,Line-count Window Location 


FS (1,23) Full screen 

H1 (1,11) Top half 

H2 (13,11) Bottom half 

T1 (1,7) Top third 

T2 (9,7) Middle third 

T3 (17,7) Bottom third 
Q1 (1,5) Top quarter 
Q2 (7,5) Second quarter 
Q3 (13,5) Third quarter 
Q4 (19,5) Bottom quarter 
$1 (1,3) Top sixth 

$2 (5,3) Second sixth 
S3 (9,3) Third sixth 

$4 | (13,3) Fourth sixth 
$5 (17,3) Fifth sixth 

36 (21,3) Bottom sixth 
E1 (1,2) Top eighth 

E2 (4,2) Second eighth 
E3 (7,2) Third eighth 


E4 (10,2) Fourth eighth 
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Window Name Start-line,Line-count Window Location 


E5 (13,2) Fifth eighth 

E6 (16,2) Sixth eighth 
E7 (19,2) Seventh eighth 
E8 (22,2) Bottom eighth 
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Built-In Symbols and Logical Names 


This appendix identifies all of the debugger built-in symbols and logical 
names. 


SS$_DEBUG Condition 


Logical Names 


SS$_DEBUG (defined in SYS$LIBRARY:STARLET.OLB) is a condition 
you can signal from your program to invoke the debugger. Signaling SS$_ 
DEBUG from your program is equivalent to typing CTRL/Y followed by 
the DCL command DEBUG at that point. 


You can pass commands to the debugger at the time you signal it with 
SS$_DEBUG. The commands you want the debugger to execute should 

be specified as you would enter them at the DBG> prompt. Multiple 
commands should be separated by semicolons. The commands should be 
passed by reference as an ASCIC string. See your language documentation 
for details on constructing an ASCIC string. 


For example, to invoke the debugger and enter a SHOW CALLS command 
at a given point in your program, you could insert the following code in 
your program (BLISS example): 


LIBSSIGNAL(SS$_DEBUG, 1, UPLIT BYTE(%ASCIC ’SHOW CALLS’)); 


You can obtain the definition of SS$_DEBUG at compile time from 

the appropriate STARLET or SYSDEF file for your language (for 
example STARLET.L32 for BLISS or FORSYSDEF.TLB for FORTRAN). 
You can also obtain the definition of SS$ DEBUG at link time in 
SYS$LIBRARY:STARLET.OLB (this method is less desirable). 





The following list identifies debugger-specific logical names. 


Logical 
Name Description 
DBGSINIT Points to your debugger initialization file. Default: no 


debugger initialization file. DBGS$INIT accepts a full or 
partial VMS file specification as well as a search list. See 
Section 8.2 for information about debugger initialization files. 
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Logical 
Name Description 
DBGSINPUT Points to the debugger input device. Default: SYS$INPUT. 


See Section 9.2 for information about using DBG$INPUT 
and DBG$OUTPUT to debug screen-oriented programs at 
two terminals. 


DBGS$INPUT is ignored in the DECwindows interface (see 
DBG$DECWS$DISPLAY). You can use DBG$INPUT if you 
are displaying the debugger’s command interface in a 
DECterm window (see Section 1.6.3.3). 


DBG$OUTPUT Points to the debugger output device. Default: 
SYS$OUTPUT. See Section 9.2 for information about using 
DBG$INPUT and DBG$OUTPUT to debug screen-oriented 
programs at two terminals. 


DBG$OUTPUT is ignored in the DECwindows interface 
(see DBGSDECWS$DISPLAY). You can use DBGSOUTPUT 
if you are displaying the debugger’s command interface in a 
DECterm window (see Section 1.6.3.3). 

DBG$PROCESS Specifies the debugging configuration (default or 
multiprocess). Default: DBG$PROCESS is undefined. See 
Section 10.2.1 for information about using DBGSPROCESS 
to specify the debugging configuration. 

DBG$DECWS$DISPLAY Applies only to workstations running DECwindows. 
Specifies the debugger interface (DECwindows 
or command) or the display device. Default: 
DBG$DECWSDISPLAY is either undefined or has the 
same definition as the application-wide logical name 
DECWS$DISPLAY. See Section 1.6.3 for information about 
using DBG$DECWSDISPLAY to override the debugger’s 
default interface in the DECwindows environment. 


Use the DCL command DEFINE or ASSIGN to assign values to these 
logical names. For example, the following command specifies the location 
of the debugger initialization file: 


$ DEFINE DBGSINIT DISKS: [JONES.COMFILES]DEBUGINIT.COM 


Note the following points about the logical name DBG$INPUT. If you 
plan to debug a program that takes its input from a file (for example, 
PROG_IN.DAT) and your debugger input from the terminal, establish the 
following definitions before invoking the debugger: 


$ DEFINE SYSSINPUT PROG IN.DAT 
S DEFINE/PROCESS DBGSINPUT ’FSLOGICAL ("SYSSCOMMAND") 


That is, define DBG$INPUT to point to the translation of 
SYS$COMMAND. If you define DBG$INPUT to point to SYS$COMMAND, 
the debugger tries to get its input from the file, PROG_IN.DAT. 
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D.3 Built-In Symbols 


The debugger’s built-in symbols provide options for specifying program 
entities and values. 


Most of the debugger built-in symbols have a percent sign (% ) prefix. 


The following symbols are described in this appendix: 


%RO to MR11, WAP, %FP, MSP, MPC, %PSL—Used to specify the VAX 
general registers. 


%VO0 to MV15, MVCR, *ZVLR, and %VMR—Used to specify the VAX 
vector registers and vector control registers. 


%NAME—Used to construct identifiers. 
%PARCNT—Used in command procedures to count parameters passed. 
%BIN, %ZDEC, %HEX, %0CT—Used to control the input radix. 


Period (.), Return key, circumflex (“), backslash (\ ), @CURLOC, 
%NEXTLOC, ZPREVLOC, %CURVAL—Used to specify consecutive 
program locations and the current value of an entity. 


Plus sign (+), minus sign (—), multiplication sign (*), division sign (/), 
at sign (@), period (.), bit field operator (<p,s,e>), LABEL, 2LINE, 
backslash (\ ) —Used as operators in address expressions. 


%ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_ 
NUMBER, “ZEXC_SEVERITY—Used to obtain information about 
exceptions. 


%ACTIVE_TASK, %2CALLER_TASK, %NEXT_TASK, TASK, 
%VISIBLE_TASK—Used to specify tasks in Ada tasking programs. 


%CURRENT_SCOPE_ENTRY, %NEXT_SCOPE_ENTRY, 
%PREVIOUS_SCOPE_ENTRY—Used to specify the current, next, 
and previous scope relative to the call stack. 


The following symbols are described elsewhere in this manual, as 
indicated: 


% ADDR, %DESCR, %REF, *%VAL—Used to specify the argument 
passing mechanism for the CALL command. See the CALL command 
description in the command dictionary. 


%PROCESS_NAME, %PROCESS_PID, %PROCESS_NUMBER, 
%NEXT_PROCESS, %PREVIOUS_PROCESS, %VISIBLE_ 
PROCESS—Used to specify processes in multiprocess programs. 
See Section 10.2.2. 


%PAGE, %WIDTH—Used to specify the current screen height and 
width. See Section C.4.1. 


%SOURCE_SCOPE, %ZINST_SCOPE—Used to specify the scope for 
source and instruction display in screen mode. See Section C.3.1 and 
Section C.3.4, respectively. 
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e 9% CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, 
%NEXTOUTPUT, SZNEXTSCROLL, ZNEXTSOURCE—Used in screen 
mode to specify displays in the display list. See Section C.4.2. 


D.3.1 Specifying the VAX Registers 


The debugger built-in symbol for a VAX register is the register name 
preceded by the percent sign (%). When specifying a register symbol, you 
can omit the percent sign (%) prefix if your program has not declared a 
symbol with the same name. 


The register symbols are identified in the following list. 


Symbol Description 
VAX General Registers 
%RO... MWR11 General purpose registers (RO ... R11) 


%AP (%R12) Argument pointer (AP) 

%FP (%R13) Frame pointer (FP) 

%SP (%R14) Stack pointer (SP) 

%PC (%R15) Program counter (PC) 

%PSL Processor status longword (PSL) 


VAX Vector Registers and Vector Control Registers | 


%VO ... %VI5 Vector registers VO... V15 


%VCR Vector count register 
%VLR Vector length register 
%VMR Vector mask register 


See Section 4.4 and Section 4.3.1 for more information about the general 
registers. See Chapter 11 for more information about the vector registers. 


D.3.2 Constructing Identifiers 


The %2NAME built-in symbol enables you to construct identifiers that are 
not ordinarily legal in the current language. The syntax is as follows: 


Y%NAME. 'character-string’ 

In the following example, the variable with the name 712’ is examined: 
DBG> EXAMINE $NAME '12’ 

In the following example, the compiler-generated label PAAA is examined: 


DBG> EXAMINE SNAME ’P.AAA’ 
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D.3.3 Counting Parameters Passed to Command Procedures 


D.3.4 


D.3.5 


The %PARCNT built-in symbol can be used within a command procedure 
that accepts a variable number of actual parameters (%PARCNT is defined 
only within a debugger command procedure). 


%PARCNT specifies the number of actual parameters passed to the current 
command procedure. In the following example, command procedure 
ABC.COM is invoked and three parameters are passed: 


DBG> @ABC 111,222,333 


Within ABC.COM, %PARCNT now has the value 3. %PARCNT is then 
used as a loop counter to obtain the value of each parameter passed to 
ABC.COM: 


DBG> FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 


Controlling the Input Radix 


The built-in symbols BIN, DEC, 2HEX, and %OCT can be used in 
address expressions and language expressions to specify that an integer 
literal that follows (or all integer literals in a parenthesized expression 
that follows) should be interpreted in binary, decimal, hexadecimal, or 
octal radix, respectively. Use these radix built-in symbols only with 
integer literals. 


For example: 
EVALUATE/DEC SHEX 10 
EVALUATE/DEC HEX (10 + 10) 
EVALUATE/DEC %BIN 10 
EVALUATE/DEC %0CT (10 + 10) 
EVALUATE/HEX %DEC 10 
SET RADIX DECIMAL 


EVALUATE %HEX 20 + 33 ! Treat 20 as hexadecimal, 33 as decimal 
! Resulting value is decimal 


EVALUATE %HEX (20+33) ! Treat both 20 and 33 as hexadecimal 
EVALUATE %HEX (20+ %OCT 10 +33) ! Treat 20 and 33 as 

! hexadecimal and 10 as octal 
SYMBOLIZE %HEX 27C9E3 ! Symbolize a hexadecimal address 
DEP/INST %HEX 5432 = 'MOVL *O%DEC 222, Ri’ 


! Treat address 5432 as hexadecimal, and operand 222 as decimal) 


Specifying Program Locations and the Current Value of an Entity 


The following built-in symbols enable you to specify program locations and 
the current value of an entity. 
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Symbol Description 

%CURLOC Current logical entity—the program location Jast referenced by an 
. (period) EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command. 
%NEXTLOC Logical successor of the current entity—the program location that 
Return key logically follows the location last referenced by an EXAMINE, 


DEPOSIT, or EVALUATE/ADDRESS command. Because the 
Return key is a command terminator, it can be used only 
where a command terminator is appropriate (for example, 
immediately after EXAMINE, but not immediately after DEPOSIT 
or EVALUATE/ADDRESS). 


%PREVLOC Logical predecessor of current entity—the program location that 

(circumflex) logically precedes the location last referenced by an EXAMINE, 
DEPOSIT, or EVALUATE/ADDRESS command. 

%CURVAL Value last displayed by an EVALUATE or EXAMINE command, or 

\ (backslash) deposited by a DEPOSIT command. These two symbols are not 


affected by an EVALUATE/ADDRESS command. 


In the following example, the variable WIDTH is examined; the value 12 
is then deposited into the current location (WIDTH); this is verified by 
examining the current location: 


DBG> EXAMINE WIDTH 
MOD\WIDTH: 7 

DBG> DEPOSIT . = 12 
DBG> EXAMINE . 
MOD\WIDTH: 12 

DBG> EXAMINE %CURLOC 
MOD\WIDTH: 12 

DBG> 


In the next example, the next and previous locations in an array are 
examined: 


DBG> EXAMINE PRIMES (4) 

MOD\PRIMES (4): 7 

DBG> EXAMINE cNEXTLOC 

MOD\PRIMES (5): 11 

DBG> EXAMINE ! Examine next location 
MOD\PRIMES (6): 13 : 
DBG> EXAMINE %PREVLOC 

MOD\PRIMES (5): 11 

DBG> EXAMINE %* 

MOD\PRIMES (4): 7 

DBG> 


Note that using the Return key to signify the logical successor does not 
apply to all contexts. For example, you cannot press the Return key after 
typing the command DEPOSIT to indicate the next location, whereas you 
can always use the symbol %NEXTLOC for that purpose. 
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D.3.6 Using Symbols and Operators in Address Expressions 


The symbols and operators that can be used in address expressions are 
listed below. A unary operator has one operand. A binary operator has 


two operands. 


Symbol 


%LABEL 


%LINE 


\ (backslash) 


At sign (@) 


Period (.) 


Bit field <p,s,e> 


Plus sign (+) 


Minus sign (—) 


Multiplication sign (*) 


Division sign (/) 


Description 


Specifies that the numeric literal that follows is a program 
label (for languages like FORTRAN that have numeric 
program labels). You can qualify the label with a path 
name prefix that specifies the containing module. 


Specifies that the numeric literal that follows is a line 
number in your program. You can qualify the line number 
with a path name prefix that specifies the containing 
module. 


When used within a path name, delimits each element of 
the path name. In this context, the backslash cannot be 
the leftmost element of the complete path name. 


When used as the prefix to a symbol, specifies that the 
symbol is to be interpreted as a global symbol. In this 

context, the backslash must be the leftmost element of 
the symbol’s complete path name. 


Unary operators. In an address expression, the at sign 
(@) and period (.) each function as a "contents-of" 
operator. The "contents-of" operator causes its operand 
to be interpreted as a memory address and thus requests 
the contents of (or value residing at) that address. 


Unary operator. You can apply bit field selection to an 
address-expression. To select a bit field, you supply a bit 
offset (p), a bit length (s), and a sign extension bit (e), 
which is optional. 


Unary or binary operator. As a unary operator, indicates 
the unchanged value of its operand. As a binary | 
operator, adds the preceding operand and succeeding 
operand together. 


Unary or binary operator. As a unary operator, indicates 
the negation of the value of its operand. As a binary 
operator, subtracts the succeeding operand from the 
preceding operand. 


Binary operator. Multiplies the preceding operand by the 
succeeding operand. 


Binary operator. Divides the preceding operand by the 
succeeding operand. 
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The following examples illustrate the use of built-in symbols and operators 
in address expressions. 


%LINE and %LABEL Operators 


The following command sets a tracepoint at line 26 of the module where 
execution is currently suspended: 


DBG> SET TRACE %LINE 26 

The next command displays the source line associated with line 47: 
DBG> EXAMINE/SOURCE %LINE 47 

module MAIN 


47: procedure SWAP (X,Y: in out INTEGER) is 
DBG> 


The next command sets a breakpoint at label 10 of module MOD4: 


DBG> SET BREAK MOD4\%LABEL 10 


Path Name Operators 


The following command displays the value of the variable COUNT that 
is declared in routine ROUT2 of module MOD4. The backslash (\ ) path 
name delimiter separates the path name elements: 

DBG> EXAMINE MOD4\ROUT2\COUNT 

MOD4\ROUT2\COUNT: 12 

DBG> 


The following command sets a breakpoint on line 26 of the module 
QUEUMAN: 


DBG> SET BREAK QUEUMAN\%LINE 26 
The following command displays the value of the global symbol X: 


DBG> EXAMINE \X 


Arithmetic Operators 


The order in which the debugger evaluates the elements of an address 
expression is similar to that used by most programming languages. The 
order is determined by the following three factors, listed in decreasing 
order of precedence (first listed have higher precedence): 


1 The use of delimiters (usually parentheses or brackets) to group 
operands with particular operators 


2 The assignment of relative priority to each operator 

3. Left-to-right priority of operators 

The debugger operators are listed in decreasing order of precedence as 
follows: 

1 Unary operators ((.), (@), (+), (—)) 

2 Multiplication and division operators ((*), (/)) 


3 Addition and subtraction operators ((+), (—)) 
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For example, when evaluating the following expression, the debugger first 
adds the operands within parentheses, then divides the result by 4, then 
subtracts the result from 5. 


5—(1+5)/4 


The following command displays the value contained in the memory 
location X + 4 bytes: 


DBG> EXAMINE X + 4 


Contents-of Operator 


The following examples illustrate use of the contents-of operator. In the 
next example, the instruction at the current PC value is obtained (the 
instruction whose address is contained in the PC and which is about to 
execute): 


DBG> EXAMINE .%PC 
MOD\S$LINE 5: PUSHL S*#8 
DBG> 


In the next example, the source line at the PC value one level down the 
call stack is obtained (at the call to routine SWAP): 


DBG> EXAMINE/SOURCE .1\%PC 
module MAIN 

MAIN\SLINE 134: SWAP (X,Y); 
DBG> 


For the next example, assume that the value of pointer variable PTR is 
7FF00000 hexadecimal, the address of an entity that you want to examine. 
Assume further that the value of this entity is 3FF00000 hexadecimal. 
The following command shows how to examine the entity: 


DBG> EXAMINE/LONG .PTR 
7TFFOO000: 3FF0O0000 
DBG> 


In the next example, the contents-of operator (at sign or period) is used 
with the current location operator (period) to examine a linked list of 
three quadword-integer pointer variables (identified as L1, L2, and L3 in 
the illustration that follows). P is a pointer to the start of the list. The 
low longword of each pointer variable contains the address of the next 
variable; the high longword of each variable contains its integer value (8, 
6, and 12, respectively). 
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DBG> SET TYPE QUADWORD; SET RADIX HEX 


DBG> EXAMINE .P 


! Examine the entity whose address 
! is contained in P. 


O0O009BC2: 00000008 OO009BDA ! High word has value 8, low word 


DBG> EXAMINE @. 


! has address of next entity (9BDA). 
! Examine the entity whose address 
! is contained in the current entity. 


OOOO9BDA: 00000006 OOD09BF4 ! High word has value 6, low word 


DBG> EXAMINE 


! has address of next entity (9BF4). 
! Examine the entity whose address 
! is contained in the current entity. 


OOOO9BF4: OOOOODOC OOD00000 ! High word has value 12 (dec.), low word 


! has address 0 (end of list). 


Bit-Field Operator 


The following example shows how to use the bit-field operator. For 
example, to examine the address expression X_NAME starting at bit 
3 with a length of 4 bits and no sign extension, you would enter the 
following command: 


DBG> EXAMINE X NAME <3,4,0> 


D.3.7 Obtaining Information About Exceptions 
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The following built-in symbols enable you to obtain information about 
the current exception and use that information to qualify breakpoints or 
tracepoints. 





Symbol Description 


%EXC_FACILITY Name of facility that issued the current exception 
%EXC_NAME Name of current exception 


%ADAEXC_NAME Ada exception name of current exception (for Ada programs 
only) | 


%EXC_NUMBER Number of current exception 
%EXC_SEVERITY Severity code of current exception 


For example: 


DBG> EVALUATE %EXC_NAME 
"PLTDIV_F" 
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NAME = "FLTDIV_F") 


DBG> EVALUATE SEXC_ NUMBER 

12 

DBG> EVALUATE/CONDITION VALUE SEXC_ NUMBER 

SSYSTEM-F-ACCVIO, access violation at PC !XL, virtual address !XL 
DBG> SET BREAK/EXCEPTION WHEN (SEXC_ NUMBER = 12) 


Note that the conditional expressions in the WHEN clauses are language- 
specific. 


Built-In Symbols and Logical Names 
D.3 Built-in Symbols 


D.3.8 Specifying Ada Tasks 


D.3.9 


The following built-in symbols can be used to specify the tasks of an Ada 
tasking program in debugger commands (these built-in symbols apply only 
to Ada tasking programs). 


Symbol Description 


%ACTIVE_TASK Currently active task—the task that executes when a GO or 
STEP command is entered. 


%CALLER_TASK Task that is the entry caller of the active task during a task 


rendezvous. 

%NEXT_TASK Next task on debugger’s task list after the task that is currently 
visible. 

%TASK n Specifies a task by means of its task ID (n is a decimal integer 
assigned by the VAX Ada Run-Time Library to each task as it is 
created). 


%VISIBLE_TASK Currently visible task—the task that is the context for an 
EXAMINE command, for example. 


Two examples follow. See the VAX Ada documentation for additional 
details. . 


DBG> EXAMINE MONITOR_TASK 
MOD\MONITOR_ TASK: %TASK 2 
DBG> WHILE sNEXT TASK NEQ SACTIVE DO (SET TASK sNEXT TASK; SHOW CALLS) 


Specifying the Current, Next, and Previous Scope on the Call Stack 


You can use the following built-in symbols to obtain and manipulate the 
scope for symbol lookup and for source or instruction display relative to 
the routine call stack. 


Symbol Description 
%CURRENT_SCOPE_ The call frame that the debugger is currently using as 
ENTRY reference when displaying source code or decoded 


VAX instructions, or when searching for symbols. By 
default, this is call frame 0. 


%NEXT_SCOPE_ENTRY The next call frame down the call stack from the call 
frame denoted by %CURRENT_SCOPE_ENTRY. 


%PREVIOUS SCOPE _ The next call frame up the call stack from the call 
ENTRY frame denoted by %CURRENT_SCOPE_ENTRY. 


These symbols return integer values that denote a call frame on the call 
stack. Call frame 0 denotes the routine at the top of the stack, where 
execution is suspended. Call frame 1 denotes the calling routine, and so 
on. 
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For example, the following command specifies that the debugger search for 
symbols starting with the scope denoted by the next routine down the call 
stack (rather than starting with the routine at the top of the call stack): 


DBG> SET SCOPE/CURRENT %NEXT SCOPE ENTRY 


FE $$ Summary of Debugger Support for Languages 


The debugger supports most of the VAX-supported languages. Debugger 
support is summarized in this chapter for the following language keywords 
(used with the SET LANGUAGE command): ADA, BASIC, BLISS, C, 
COBOL, DIBOL, FORTRAN, MACRO, PASCAL, PLI, RPG, SCAN, and 
UNKNOWN. For each language, the following information is provided: 


¢ Supported operators in language expressions 
e Supported constructs in language expressions and address expressions 
e Supported data types 


e Any other language-specific features (for example, event keywords in 
the case of Ada and SCAN) 


e Restrictions in debugger support, if any 


For further information, refer to the documentation furnished with a 
particular language. 





E.1 Ada 


This section includes information about debugger support for Ada. 


Operators in Language Expressions 


Supported Ada operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus (identity) 

Prefix - Unary minus (negation) 

Infix + Addition 

Infix ~ Subtraction 

Infix . Multiplication 

Infix / Division 

Infix MOD Modulus 

Infix REM Remainder 

Infix Exponentiation 

Prefix ABS Absolute value 

Infix & Concatenation (only string types) 

Infix = Equality (only scalar and string types) 
Infix |= Inequality (only scalar and string types) 
Infix > Greater than (only scalar and string types) 
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Kind Symbol Function 

Infix >= Greater than or equal (only scalar and string types) 
Infix < Less than (only scalar and string types) 

Infix <= Less than or equal (only scalar and string types) 
Prefix NOT Logical NOT 

Infix AND Logical AND (not for bit arrays) 

Infix OR Logical OR (not for bit arrays) 

Infix XOR Logical exclusive OR (not for bit arrays) 


The debugger does not support the following items: 

e Operations on entire arrays or records 

¢ The short-circuit control forms: and then, or else 
e The membership tests: in, not in 


¢ User-defined operators 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for Ada follow: 


Symbol Construct 


() Subscripting 
Record component selection 
-ALL Pointer dereferencing 


Predefined Symbols 
Supported Ada predefined symbols follow: 


Symbol Meaning 


TRUE Boolean True 
FALSE Boolean False 
null Null access value 
Data Types 


Supported Ada data types follow: 


Ada Type VAX Type Name 
INTEGER Longword Integer (L) 
SHORT_INTEGER Word Integer (W) 
SHORT_SHORT_INTEGER Byte Integer (B) 


SYSTEM.UNSIGNED_QUADWORD Quadword Unsigned (QU) 
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Ada Type 


SYSTEM.UNSIGNED_LONGWORD 
SYSTEM.UNSIGNED_WORD 
SYSTEM.UNSIGNED_BYTE 


FLOAT 
SYSTEM.F_FLOAT 
SYSTEM.D_FLOAT 
LONG_FLOAT 


SYSTEM.G_FLOAT 
SYSTEM.H_FLOAT 
LONG_LONG_FLOAT 
Fixed 

STRING 

BOOLEAN 

BOOLEAN 
Enumeration 


Arrays 

Records 

Access (pointers) 
Tasks 


Predefined Attributes 
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VAX Type Name 


Longword Unsigned (LU) 
Word Unsigned (WU) 
Byte Unsigned (BU) 
F_Floating (F) 
F_Floating (F) 

D_ Floating (D) 


D_ Floating (D), if pragma LONG_FLOAT 
(D_FLOAT) is in effect. G_Floating (G), if 
pragma LONG_FLOAT(G_FLOAT) is in effect. 


G_Floating (G) 
H_Floating (H) 
H_Floating (H) 

(None) 

ASCII Text (T) 

Aligned Bit String (V) 
Unaligned Bit String (VU) 


For any enumeration type whose value fits 
into an unsigned byte or word: Byte Unsigned 
(BU) or Word Unsigned (WU), respectively. 
Otherwise: No corresponding VAX data type. 


(None) 
(None) 
(None) 
(None) 


Supported Ada predefined attributes follow: 


Attribute 
P* CONSTRAINED 


P’ FIRST 


P’ FIRST 


Debugger Support 


For a prefix P that denotes a record object with discriminants. 
The value of P’7’ CONSTRAINED reflects the current state of P 
(constrained or unconstrained). 


For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the lower bound of P. 


For a prefix P that is appropriate for an array type, or that 


denotes a constrained array subtype. Yields the lower bound of 
the first index range. 


P’ FIRST(N) 


For a prefix P that is appropriate for an array type, or that 


denotes a constrained array subtype. Yields the lower bound of 
the N-th index range. 


P’ LAST 


For a prefix P that denotes an enumeration type, or a subtype of 


an enumeration type. Yields the upper bound of P. 
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Attribute 


P’ LAST 


P’ LAST(N) 


P’ LENGTH 


P’ LENGTH(N) 


P’ POS(X) 


P’ PRED(X) 


P’ SIZE 


P’ SUCC(X) 


P’ VAL(N) 


Tasking States 


Debugger Support 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper bound of 
the first index range. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper bound of 
the N-th index range. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of 
values of the first index range (zero for a null range). 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of 
values of the N-th index range (zero for a null range). 


For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the position number of the value X. 
The first position is 0. 


For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which has a 
position number one less than that of X. 


For a prefix P that denotes an object. Yields the number of bits 
allocated to hold the object. 


For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which has a 
position number one more than that of X. 


For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the value of type P which has the 
position number N. The first position is 0. | 


Support for Ada tasking states is as follows. 


The following task-state keywords can be used with the SHOW TASK 
/STATE command: 





Task State 


RUNNING 
READY 


SUSPENDED 


TERMINATED 


Description 


Currently running on the processor. This is the active task. 


Eligible to execute and waiting for the processor to be made 
available. 


Suspended—that is, waiting for an event rather than for the 
availability of the processor. For example, when a task is created, it 
remains in the suspended state until it is activated. 


Terminated. 
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The following task-substate keywords can appear in a SHOW TASK 


display: 


Task Substate 


Abnormal 
Accept 


Activating 
Activating tasks 
Completed [abn] 


Completed [exc] 


Completed 


Delay 
Dependents 
Dependents [exc] 


Entry call 

Invalid state 

/O or AST 

Not yet activated 
Select or delay 


Select or term. 
Select 


Shared resource 
Terminated [abn] 
Terminated [exc] 
Terminated 

Timed entry call 


Description 


Task has been aborted. 


Task is waiting at an accept statement that is not inside a 
select statement. 


Task is elaborating its declarative part. 
Task is waiting for tasks it has created to finish activating. 


Task is completed due to an abort statement, but is not yet 
terminated. In Ada, a task awaiting dependent tasks at its 
“end” is called “completed”. After the dependent tasks are 
terminated, the state changes to terminated. 


Task is completed due to an unhandled exception, but is not 
yet terminated. In Ada, a task awaiting dependent tasks at 
its “end” is called “completed”. After the dependent tasks 
are terminated, the state changes to terminated. 


Task is completed. No abort statement was issued, and no 
unhandled exception occurred. 


Task is waiting at a delay statement. 
Task is waiting for dependent tasks to terminate. 


Task is waiting for dependent tasks to allow an unhandled 
exception to propagate. 


Task is waiting for its entry call to be accepted. 

There is a bug in the VAX Ada Run-Time Library. 

Task is waiting for /O completion or some AST. 

Task is waiting to be activated by the task that created it. 


Task is waiting at a select statement with a delay 
alternative. 


Task is waiting at a select statement with a terminate 
alternative. 


Task is waiting at a select statement with neither an else, 
delay, or terminate alternative. 


Task is waiting for an internal shared resource. 

Task was terminated by an abort. 

Task was terminated because of an unhandled exception. 
Task terminated normally. 

Task is waiting in a timed entry call. 





Events 


The following Ada event keywords can be used with the /EVENT qualifier 
of the SET BREAK, SET TRACE, CANCEL BREAK, and CANCEL 
TRACE commands. You can also display these event keywords with 

the SHOW EVENT _ FACILITY command. 
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Exception-Related Events 


Event Keyword 


HANDLED 


HANDLED_OTHERS 


Description 


Triggers when an exception is about to be handled 
in some Ada exception handler, including an others 
handler. 


Triggers only when an exception is about to be 
handled in an others Ada exception handler. 


Task Exception-Related Events 


Event Keyword 
RENDEZVOUS_EXCEPTION 


DEPENDENTS_EXCEPTION 


Task Termination Events 
Event Keyword 


TERMINATED 
EXCEPTION_TERMINATED 


ABORT_TERMINATED 


\ 


Description 


Triggers when an exception begins to propagate out 
of a rendezvous. 


Triggers when an unhandled exception causes a task 
to wait for dependent tasks in some scope (includes 
unhandled exceptions, such as task rundown signals, 
that are internal to the VAX Ada Run-Time Library). 
Often immediately precedes a deadlock. 


Description 
Triggers when a task is terminating, whether normally, 
by abort, or by exception. 


Triggers when a task is terminating due to an 
unhandled exception. 


Triggers when a task is terminating due to an abort. 


Low-Level Task Scheduling Events 


Event Keyword 


RUN 
PREEMPTED 


ACTIVATING 


SUSPENDED 


Restrictions 


Description 


Triggers when a task is about to run. 


Triggers when a task is being preempted from the 
RUN state, and its state changes to READY. 


Triggers when a task is about to begin its activation 
(that is, at the beginning of the elaboration of the 
declarative part of its task body). 


Triggers when a task is about to be suspended. 


Restrictions in debugger support for Ada are as follows: 


e With certain Ada record variables, the debugger fails to show the 
record components correctly (possibly with a NOACCESSR error 
message) when the type declaration is in a different scope than the 
record (symbol) declaration. 
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e You cannot examine Ada objects requiring extended descriptor DSTs 
(debug-symbol-table records) to describe them. These objects are 
typically accessed arrays whose size is greater than 65535 bytes. 





This section includes information about debugger support for BASIC. 


Operators in Language Expressions 
Supported BASIC operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix - Unary minus (negation) 
Infix + Addition, String concatenation 
Infix - Subtraction 

Infix . Multiplication 

Infix / Division 

Infix oF Exponentiation 

Infix . Exponentiation 

Infix z= Equal to 

Infix <> Not equal to 

Infix >< Not equal to 

Infix > Greater than 

Infix >= Greater than or equal to 
Infix => Greater than or equal to 
Infix < Less than 

Infix <= Less than or equal to 
Infix =< Less than or equal to 
Prefix NOT Bit-wise NOT 

Infix AND Bit-wise AND 

Infix OR Bit-wise OR 

Infix XOR Bit-wise exclusive OR 
Infix IMP Bit-wise implication 

Infix EQV Bit-wise equivalence 
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E.2 BASIC 
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Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for BASIC 
follow: 


Symbol Construct 


() Subscripting 
Record component selection 


Data Types 
Supported BASIC data types follow: 


BASIC Type VAX Type Name 


BYTE Byte Integer (B) 
WORD Word Integer (W) 
LONG Longword Integer (L) 
SINGLE F_Floating (F) 
DOUBLE D_Floating (D) 
GFLOAT G_Floating (G) 
HFLOAT H_Floating (H) 
DECIMAL Packed Decimal (P ) 
STRING ASCII Text (T) 

RFA (None) 

Arrays (None) 

Records (None) 


Additional Information 


Expressions that overflow in the BASIC language do not necessarily 

overflow when evaluated by the debugger. The debugger tries to compute 
a numerically correct result, even when the BASIC rules call for overflows. 
This difference is particularly likely to affect DECIMAL computations. 


BASIC constants of the forms [radix]‘numeric-string”’[type] (such as 
“12.34”"GFLOAT) or n% (such as 25% for integer 25) are not supported in 
debugger expressions. 
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E.3 BLISS 





This section includes information about debugger support for BLISS. 


Operators in Language Expressions 


Supported BLISS operators in language expressions follow: 


Kind 


Prefix 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 
Infix 


Symbol 


MOD 


EQL 
EQLU 
EQLA 
NEQ 
NEQU 
NEQA 
GTR 
GTRU 
GTRA 
GEQ 
GEQU 
GEQA 
LSS 
LSSU 
LSSA 
LEQ © 
LEQU 
LEQA 
NOT 
AND 
OR 
XOR 
EQV 


Function 


Indirection 

Unary plus 

Unary minus (negation) 
Addition 

Subtraction 

Multiplication 

Division 

Remainder 

Left shift 

Equal to 

Equal to 

Equal to 

Not equal to 

Not equal to 

Not equal to 

Greater than 

Greater than unsigned 

Greater than unsigned 

Greater than or equal to 
Greater than or equal to unsigned 
Greater than or equal to unsigned 
Less than 

Less than unsigned 

Less than unsigned 

Less than or equal to 

Less than or equal to unsigned 
Less than or equal to unsigned 
Bit-wise NOT 

Bit-wise AND 

Bit-wise OR 

Bit-wise exclusive OR 

Bit-wise equivalence 
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E.3 BLISS 
Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for BLISS 
follow: 
Symbol Construct 
[] Subscripting 
[fldname] Field selection 
<p,S,e> Bit field selection 
Data Types 
Supported BLISS data types follow: 
BLISS Type VAX Type Name 
BYTE Byte Integer (B) 
WORD Word Integer (W) 
LONG Longword Integer (L) 
BYTE UNSIGNED Byte Unsigned (BU) 
WORD UNSIGNED Word Unsigned (WU) 
LONG UNSIGNED Longword Unsigned (LU) 
VECTOR (None) 
BITVECTOR (None) 
BLOCK (None) 
BLOCKVECTOR (None) 
REF VECTOR (None) 
REF BITVECTOR (None) 
REF BLOCK (None) 
REF BLOCKVECTOR (None) 





This section includes information about debugger support for C. 


Operators in Language Expressions 


Supported C operators in language expressions follow: 


Kind Symbol Function 

Prefix : Indirection 

Prefix & Address of 

Prefix SIZEOF Size of 

Prefix - Unary minus (negation) 
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Kind Symbol Function 

Infix + Addition 

Infix _ Subtraction 

Infix . Multiplication 

Infix / Division 

Infix % Remainder 

Infix << Left shift 

Infix >> Right shift 

Infix ee Equal to 

Infix |= Not equal to 

Infix > Greater than 

Infix >= Greater than or equal to 
Infix < Less than 

Infix <= Less than or equal to 
Prefix (tilde) Bit-wise NOT 

Infix & Bit-wise AND 

Infix | Bit-wise OR 

Infix e Bit-wise exclusive OR 
Prefix Logical NOT 

Infix && Logical AND 

Infix | | Logical OR 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for C follow: 


Symbol Construct 


[ ] Subscripting 

Structure component selection 
-> Pointer dereferencing 
Data Types 


Supported C data types follow: 


C Type VAX Type Name 

int Longword Integer (L) 
unsigned int Longword Unsigned (LU) 
short int Word Integer (W) 
unsigned short int Word Unsigned (WU) 
char Byte Integer (B) 
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E.4C 
C Type VAX Type Name 
unsigned char Byte Unsigned (BU) 
float F_Floating (F) 
double D_ Floating (D) 
enum (None) 
struct (None) 
union (None) 
Pointer Type (None) 
Array Type (None) 
Additional Information 
Symbol names are case sensitive for language C, meaning that uppercase 
and lowercase letters are treated as different characters. 
Since the exclamation point (!) is an operator in C, it cannot be used 
as the comment delimiter. When the language is set to C, the debugger 
instead accepts /* as the comment delimiter. The comment continues 
to the end of the current line. (A matching */ is neither needed nor 
recognized.) To permit debugger log files to be used as debugger input, 
the debugger still recognizes ! as a comment delimiter if it is the first 
nonspace character on a line. 
The debugger accepts the prefix asterisk (*) as an indirection operator 
in both C language expressions and debugger address expressions. In 
address expressions, prefix “*” is synonymous to prefix “.” or “@” when the 
language is set to C. 
The debugger does not support any of the assignment operators in C (or 
any other language) in order to prevent unintended modifications to the 
program being debugged. Hence such operators as =, +=, -=, ++, and — are 
not recognized. To alter the contents of a memory location, you must do so 
with an explicit DEPOSIT command. 

COBOL 
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This section includes information about debugger support for COBOL. 


Operators in Language Expressions 


Supported COBOL operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix _ Unary minus (negation) 
Infix + Addition 

Infix _ Subtraction 

Infix Multiplication 
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Kind Symbol Function 

Infix / Division 

Infix is Exponentiation 

Infix = Equal to 

Infix NOT = Not equal to 

Infix > Greater than 

Infix NOT < Greater than or equal to 
Infix < Less than 

Infix NOT > Less than or equal to 
Infix NOT Logical NOT 

Infix AND Logical AND 

Infix OR Logical OR 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for COBOL 


follow: 

Symbol Construct 

() Subscripting 

OF Record component selection 
IN Record component selection 
Data Types 


Supported COBOL data types follow: 


COBOL Type VAX Type Name 

COMP Longword Integer (L,LU) 
COMP Word Integer (W,WU) 
COMP Quadword Integer (Q,QU) 
COMP-1 F_ Floating (F) 

COMP-2 D_Floating (D) 

COMP-3 Packed Decimal (P) 
INDEX Longword Integer (L) 
Alphanumeric ASCII Text (T) 

Records (None) 


Numeric Unsigned 

Leading Separate Sign 
Leading Overpunched Sign 
Trailing Separate Sign 
Trailing Overpunched Sign 


Numeric string, unsigned (NU) 

Numeric string, left separate sign (NL) 
Numeric string, left overpunched sign (NLO) 
Numeric string, right separate sign (NR) 
Numeric string, right overpunched sign (NRO) 
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DIBOL 


E-14 


Additional Information 


The debugger can show source text included in a program with the 
COPY, COPY REPLACING, or REPLACE verb. However, when COPY 
REPLACING or REPLACE is used, the debugger always shows the 
original source text as it appeared before text replacement. In other 
words, the original source file is shown instead of the modified source text 
generated by the COPY REPLACING or REPLACE verb. 


The debugger cannot show the original source lines associated with the 
code for a REPORT section. You can see the DATA SECTION source lines 
associated with a REPORT, but no source lines are associated with the 
compiled code that generates the report. 


This section includes information about debugger support for DIBOL. 


Operators in Language Expressions 


Supported DIBOL operators in language expressions follow: 


Kind Symbol Function 

Prefix # Round 

Prefix + Unary plus 

Prefix - Unary minus (negation) 
Infix + Addition 

Infix _ Subtraction 

Infix . Multiplication 

infix / Division 

Infix // Division with fractional result 
Infix .EQ. Equal to 

infix .NE. Not equal to 

Infix GT. Greater than 

Infix .GE: Greater than or equal to 
infix LT. Less than 

infix LE. Less than or equal to 
Infix NOT. Logical NOT 

Infix -AND. Logical AND 

Infix .OR. Logical OR 


infix .XOR. Exclusive OR 
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Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for DIBOL 
follow: 


Symbol Construct 


() Substring 
[ ] Subscripting 
Record component selection 


Data Types 
Supported DIBOL data types follow: 


DIBOL Type VAX Type Name 

1 Byte Integer (B) 

l2 Word Integer (W) 

14 Longword Integer (L) 

Pn Packed Decimal String (P) 
Pn.m Packed Decimal String (P) 

Dn Numeric String, Zoned Sign (NZ) 
Dn.m Numeric String, Zoned Sign (NZ) 
An ASCII Text (T) 

Arrays (None) 

Records (None) 





This section includes information about debugger support for FORTRAN. 


Operators in Language Expressions 


Supported FORTRAN operators in language expressions follow: 


Kind © Symbol Function 

Prefix + Unary plus 

Prefix _ Unary minus (negation) 
Infix + Addition 

Infix — Subtraction 

Infix " Multiplication 

Infix / Division 

Infix ue Exponentiation 

Infix /I Concatenation 


E-15 


summary of Debugger Support for Languages 


E.7 FORTRAN 


E-16 


Kind Symbol Function 

Infix .EQ. Equal to 

Infix .NE. Not equal to 

Infix GT. Greater than 

Infix “GE. Greater than or equal to 
Infix LT. Less than 

Infix ‘LE: Less than or equal to 
Prefix .NOT. Logical NOT 

Infix .AND. Logical AND 

infix OR. Logical OR 

Infix .XOR. Exclusive OR 

infix -EQV. Equivalence 

Infix .NEQV. Exclusive OR 


Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for FORTRAN 
follow: 

Symbol Construct 


() Subscripting 
Record component selection 


Predefined Symbols 
Supported FORTRAN predefined symbols follow: 


Symbol Description 
. TRUE. Logical True 
-FALSE. Logical False 
Data Types 


Supported FORTRAN data types follow: 


FORTRAN Type VAX Type Name 


LOGICAL*1 Byte Unsigned (BU) 
LOGICAL*2 Word Unsigned (WU) 
LOGICAL*4 Longword Unsigned (LU) 
INTEGER*2 Word Integer (W) 
INTEGER*4 Longword Integer (L) 
REAL*4 F Floating (F) 
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FORTRAN Type VAX Type Name 
REAL*8 D_Floating (D) 
REAL*8 G_Floating (G) 
REAL*16 H_Floating (H) 
COMPLEX*8 F_Complex (FC) 
COMPLEX*16 D_ Complex (DC) 
COMPLEX*16 G_Complex (GC) 
CHARACTER ASCII Text (T) 
Arrays (None) 

Records (None) 


Additional Information 


Even though the VAX type codes for unsigned integers (BU, WU, LU) are 
used internally to describe the LOGICAL data types, the debugger (like 
the compiler) treats LOGICAL variables and values as being signed when 
used in language expressions. 


The debugger prints the numeric values of LOGICAL variables or 
expressions instead of TRUE or FALSE. Normally, only the low-order bit of 
a LOGICAL variable or value is significant (0 is FALSE and 1 is TRUE). 
However, VAX FORTRAN does allow all bits in a LOGICAL value to be 
manipulated and LOGICAL values can be used in integer expressions. For 
this reason, it is at times necessary to see the entire integer value of a 
LOGICAL variable or expression, and that is what the debugger shows. 


COMPLEX constants such as (1.0,2.0) are not supported in debugger 
expressions. 





This section includes information about debugger support for MACRO. 


Operators in Language Expressions 


Language MACRO does not have expressions in the same sense as high- 
level languages. Only assembly-time expressions and only a limited set 
of operators are accepted. To permit the MACRO programmer to use 
expressions at debug-time as freely as in other languages, the debugger 
accepts a number of operators in MACRO language expressions that are 
not found in MACRO itself. In particular, the debugger accepts a complete 
set of comparison and Boolean operators modeled after BLISS. It also 
accepts the indirection operator and the normal arithmetic operators. 


Kind Symbol Function 

Prefix @ Indirection 
Prefix : Indirection 
Prefix + Unary plus 
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Kind 


Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 
Infix 


Symbol 


Function 


Unary minus (negation) 
Addition 

Subtraction 
Multiplication 

Division 

Remainder 

Left shift 

Equal to 

Equal to 

Not equal to 

Not equal to 

Greater than 

Greater than unsigned 
Greater than or equal to 
Greater than or equal to unsigned 
Less than 

Less than unsigned 
Less than or equal to 
Less than or equal to unsigned 
Bit-wise NOT 

Bit-wise AND 

Bit-wise OR 

Bit-wise exclusive OR 
Bit-wise equivalence 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for MACRO 


follow: 


Symbol 


[] 


<p,S,e> 


Construct 


Subscripting 


Bitfield selection as in BLISS 


The DST information generated by the MACRO assembler treats a label 
that is followed by an assembler directive for storage allocation as an 
array variable whose name is the label. This enables you to use the array 
syntax of a high-level language when examining or manipulating such 


data. 


In the following example of MACRO source code, the label LAB4 
designates hexadecimal data stored in four words: 


LAB4: 


.WORD 


AX3F,5[2],“X38C 
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The debugger treats LAB4 as an array variable. For example, the next 
command displays the value stored in each element (word): 


DBG> EXAMINE LAB4 
. MAIN. \MAIN\LAB4 


[O]: O03F 
[1]: 0005 
[2]: 0005 
eS ie O03C 


DBG> 


The next command displays the value stored in the fourth word (the first 
word is indexed as element “0Q”): 


DBG> EXAMINE LAB4 [3] 
. MAIN. \MAIN\LAB4 [3]: O03C 
DBG> 


Data Types 
Supported MACRO data types follow: 


MACRO Type 


(Not applicable) 
(Not applicable) 
(Not applicable) 
(Not applicable) 
(Not applicable) 
Not applicable) 
Not applicable) 
Not applicable) 


Not applicable) 


( 
( 
( 
(Not applicable) 
( 
(Not applicable) 


VAX Type Name 


Byte Unsigned (BU) 
Word Unsigned (WU) 
Longword Unsigned (LU) 
Byte Integer (B) 
Word Integer (W) 
Longword Integer (L) 
F_Floating (F) 
D_Floating (D) 
G_Floating (G) 
H_Floating (H) 
Packed decimal (P ) 





This section includes information about debugger support for Pascal. 


Operators in Language Expressions 


Supported Pascal operators in language expressions follow: 


Kind Symbol 
Prefix + 
Prefix ~ 
Infix + 
Infix — 


Function 

Unary plus 

Unary minus (negation) 
Addition, concatenation 
Subtraction 
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Kind Symbol Function 

Infix ° Multiplication 

Infix / Real division 

Infix DIV Integer division 

Infix MOD Modulus 

Infix REM Remainder 

Infix ws Exponentiation 

Infix IN Set membership 

Infix = Equal to 

Infix <> Not equal to 

Infix > Greater than 

Infix >= Greater than or equal to 
Infix < Less than 

Infix <c Less than or equal to 
Prefix NOT Logical NOT 

Infix AND Logical AND 

Infix OR Logical OR 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for Pascal 
follow: 
Symbol Construct 


[ ] Subscripting 
Record component selection 
m Pointer dereferencing 


Predefined Symbols 
Supported Pascal predefined symbols follow: 


Symbol Meaning 


TRUE Boolean True 
FALSE Boolean False 
NIL Nil pointer 
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Supported Pascal built-in functions follow: 


Symbol 
SUCC 


Meaning 


Logical successor 


PRED Logical predecessor 


Data Types 


Supported Pascal data types follow: 


Pascal Type VAX Type Name 
INTEGER Longword Integer (L) 
INTEGER Word Integer (W,WU) 
INTEGER Byte Integer (B,BU) 
UNSIGNED Longword Unsigned (LU) 
UNSIGNED Word Unsigned (WU) 
UNSIGNED Byte Unsigned (BU) 
SINGLE F_Floating (F) 
DOUBLE D_ Floating (D) 
DOUBLE G_Floating (G) 
QUADRUPLE H_Floating (H) 
BOOLEAN (None) 

CHAR ASCII Text (T) 
VARYING OF CHAR Varying Text (VT) 
SET (None) 

FILE (None) 

Enumerations (None) 

Subranges (None) 

Typed Pointers (None) 

Arrays (None) 

Records (None) 

Variant records (None) 


The debugger accepts Pascal set constants such as [1,2,5,8. 10] or [RED, 
BLUE] in Pascal language expressions. 


Restrictions 


Restrictions in debugger support for Pascal are as follows. 
You cannot examine the .LENGTH and .BODY fields of a Pascal varying 


string variable using the normal language syntax. For example, if VARS is 
the name of a string variable, the following commands are not supported: 


DBG> EXAMINE VARS. LENGTH 
DBG> EXAMINE VARS.BODY 
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E.9 Pascal 
To examine these fields, use the techniques illustrated in the following 
examples. 
Use Instead of 
EXAMINE/WORD VARS EXAMINE VARS.LENGTH 
EXAMINE/ASCII VARS+2 EXAMINE VARS.BODY 
E.10 #£PLI/I 


This section includes information about debugger support for PL/I. 


Operators in Language Expressions 


Supported PL/I operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix _ Unary minus (negation) 
Infix + Addition 

Infix — Subtraction 

Infix Multiplication 

Infix / Division 

Infix ne Exponentiation 

Infix | | Concatenation 

Infix = Equal to 

Infix A= Not equal to 

Infix > Greater than 

Infix >= Greater than or equal to 
infix Ne Greater than or equal to 
Infix < Less than 

infix <= Less than or equal to 
Infix SS Less than or equal to 
Prefix ° Bit-wise NOT 

Infix & Bit-wise AND 


Infix | Bit-wise OR 
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Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for PL/I follow: 


Symbol Construct 


() Subscripting 

Structure component selection 
-> Pointer dereferencing 
Data Types 


Supported PL/I data types follow: 


PL/I Type VAX Type Name 
FIXED BINARY Longword Integer (L) 
FIXED DECIMAL Packed Decimal (P) 
FLOAT BINARY F_Floating (F) 
FLOAT DECIMAL F_Floating (F) 
FLOAT BIN/DEC D_ Floating (D) 
FLOAT BIN/DEC G_Floating (G) 
FLOAT BIN/DEC H_ Floating (H) 

BIT Bit (V) 

BIT Bit Unaligned (VU) 
CHARACTER ASCII Text (T) 
CHARACTER VARYING Varying Text (VT) 
FILE (None) — 

Labels (None) 

Pointers (None) 

Arrays (None) 

Structures (None) 


The debugger treats all numeric constants of the form n or n.n in PL/I 
language expressions as packed decimal constants, not integer or floating- 
point constants, in order to conform to PL/I language rules. The internal 
representation of 10 is therefore 0C0O1 hexadecimal, not 0A hexadecimal. 


You can enter floating-point constants using the syntax nEn or n.nEn. 


There is no PL/I syntax for entering constants whose internal 
representation is Longword Integer. This limitation is not normally 
significant when debugging, since the debugger supports the PL/I type 
conversion rules. However, it is possible to enter integer constants by 
using the debugger’s % HEX, %OCT, and %BIN operators. 
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RPG 


This section includes information about debugger support for RPG. 


Operators in Language Expressions 


Supported RPG operators in language expressions follow: 


Kind Symbol Function 


Prefix + Unary plus 

Prefix — Unary minus (negation) 
Infix + Addition 

Infix - Subtraction 

Infix : Multiplication 

Infix / Division 

Infix = Equal to 

Infix NOT = Not equal to 

Infix > Greater than 

Infix NOT < Greater than or equal to 
Infix < Less than 

Infix NOT > Less than or equal to 
Prefix NOT Logical NOT 

Infix AND Logical AND 

Infix OR Logical OR 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for RPG follow: 


Symbol Construct 
() Subscripting 
Data Types 


Supported RPG data types follow: 


RPG Type VAX Type Name 

Longword Longword Integer (L) 

Word Word Integer (W) 

Packed Decimal | Packed Decimal (P) 

Character ASCII Text (T) 

Overpunched Decimal Right Overpunched Sign (NRO) 
Arrays (None) 

Tables (None) 
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E.11 RPG 


The debugger supports access to all RPG indicators and labels used in 
the current program. You can thus examine labels such as *DETL and 
indicators such as *INLR and *INO1 to *INQ9. 





This section includes information about debugger support for SCAN. 


Operators in Language Expressions 


Supported SCAN operators in language expressions follow: 


Kind 


Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 


Symbol 


+ 


Function 


Unary plus 

Unary minus (negation) 
Addition 

Subtraction 
Multiplication 

Division 

Concatenation 

Equal to 

Not equal to 

Greater than 

Greater than or equal to 
Less than 

Less than or equal to 
Complement 
Intersection 

Union 


Exclusive OR 


Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for SCAN 


follow: 


Symbol 
() 


Construct 


Subscripting 


Record component selection 


Pointer dereferencing 
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Predefined Symbols 
Supported SCAN predefined symbols follow: 


Symbol Meaning 


TRUE Boolean True 
FALSE Boolean False 
NIL Nil pointer 
Data Types 


Supported SCAN data types follow: 


SCAN Type VAX Type Name 
BOOLEAN (None) 

INTEGER Longword Integer (L) 
POINTER (None) 

FIXED STRING (n) TEXT with CLASS=S 
VARYING STRING (n) TEXT with CLASS=VS 
DYNAMIC STRING TEXT with CLASS=D 
TREE (None) 

TREEPTR (None) 

RECORD (None) 

OVERLAY (None) 


There is no specific support for the following datatypes: FILE, TOKEN, 
GROUP, SET. Examining a FILL variable displays the contents of the 
specified variable as a string by default, and so might have little meaning. 
If the characteristics of the fill are known, then the appropriate qualifier 
(/HEX, and so on) applied to the command produces a more meaningful 
display. 


The following examples show how to examine SCAN TREE and TREEPTR 
variables. To dump an entire SCAN tree or subtree: 


DBG> EXAMINE tree variable([subscript], ... ) 
To dump the contents of a SCAN subtree: 

DBG> EXAMINE treeptr variable 

To dump an entire SCAN subtree: 

DBG> EXAMINE treeptr variable-> 


DEPOSIT is not supported for SCAN TREE variables. You can set 
breakpoints on any SCAN label, line number, MACRO, or PROCEDURE. 
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Events 


E.12 SCAN 


The following SCAN event keywords can be used with the /EVENT 
qualifier of the SET BREAK, SET TRACE, CANCEL BREAK, and 
CANCEL TRACE commands. You can also display these event keywords 
with the SHOW EVENT_FACILITY command. 


Event Keyword 


TOKEN 
PICTURE 
INPUT 
OUTPUT 
TRIGGER 
SYNTAX 
ERROR 


Language UNKNOWN 


Description 


A token is built. 

An operand in a picture is being matched. 

A new line of the input stream is read. 

A new line of the output stream is written. 

A trigger macro is starting or terminating. 

A syntax macro is starting or terminating. 

Picture matching error recovery is starting or terminating. 


This section includes information about debugger support for UNKNOWN. 


Operators in Language Expressions 


Supported operators in language expressions for UNKNOWN follow: 


Kind 


Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 


Symbol 


+ 


Function 


Unary plus 


Unary minus (negation) 
Addition 

Subtraction 
Multiplication 

Division 

Exponentiation 
Concatenation 
Concatenation 

Equal to 

Not equal to 

Not equal to 

Greater than 

Greater than or equal to 
Less than 

Less than or equal to 
Equal to 

Not equal to 
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Kind Symbol Function 

Infix GTR Greater than 

Infix GEQ Greater than or equal to 
infix LSS Less than 

Infix LEQ Less than or equal to 
Prefix NOT Logical NOT 

Infix AND Logical AND 

Infix OR Logical OR 

Infix XOR Exclusive OR 

Infix EQV Equivalence 


Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for UNKNOWN 
follow: 

Symbo! Construct 


[] Subscripting 
() Subscripting 

Record component selection 
‘ Pointer dereferencing 


Predefined Symbols 
Supported predefined symbols for UNKNOWN follow: 


Symbol Meaning 


TRUE Boolean True 
FALSE Boolean False 
NIL Nil pointer 
Data Types 


When the language is set to UNKNOWN, the debugger understands all 
data types accepted by other languages except a few very language-specific 
types, such a picture types and file types. In UNKNOWN language 
expressions, the debugger accepts most scalar VAX Standard data types. 


e For language UNKNOWN, the debugger accepts the dot-notation for 
record component selection. If C is a component of a record B which 
in turn is a component of a record A, C can be referenced as “A.B.C”. 
Subscripts can be attached to any array components; if B is an array, 
for instance, C can be referenced as “A.B[2,3].C”. 


e For language UNKNOWN, the debugger accepts both round and 
square subscript parentheses. Hence, A[2,3] and A(2,3) are equivalent. 
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A 


Abort function * 2-8, 10-10, CD-38, CD-127, 
CD-209 
with DECwindows « 1-21 
/ABORT qualifier * CD-182 
/AC 
See /ASCIC qualifier 
/ACTIVATING qualifier * 10-14, CD-—17, CD-30, 
CD-131, CD-188 
Activation 
predefined tracepoint, multiprocess program « 
10-14 
/ACTIVE qualifier» CD-182 
%ACTIVE_TASK « D—-11 
/AD 
See /ASCID qualifier 
%ADAEXC_NAME « 9-16, D—10 
Address 
depositing into * 4—25 
with DECwindows « 1-26 
examining * 4—14 
with DECwindows « 1-26 
obtaining * 3-13, 4-13 
with DECwindows « 1-26 
specifying breakpoint * 3-13 
symbolizing * 4—14 
with DECwindows « 1-26 
Address expression 


See also Address 
code * 4—20, 6—5 
with DECwindows « 1-23 
compared to language expression * 4-8 
with DECwindows « 1-23 
composite, vector * 11-18 
current entity * 4-8, 4-13, D-5 
with DECwindows « 1—9 
DEPOSIT command « 4-3, CD-61 
EVALUATE/ADDRESS command « 3-13, 4—13, 
CD-83 
EXAMINE command « 4-2, CD-—85 
EXAMINE/SOURCE command « 6-5 
logical predecessor * 4-8, 4-13, D-5 
with DECwindows « 1—9 
logical successor * 4~8, 4-13, D-5 
—— with DECwindows « 1—9 


Address expression (Cont.) 


selecting from DECwindows window » 1—23 
SET BREAK command « 3-9, CD-130 
SET TRACE command « 3-10, CD—187 
SET WATCH command « 3-17, CD-—200 
symbolic * 4—4 
with DECwindows « 1-23 
SYMBOLIZE command « 4-14, CD-271 
type of « 4—4 
/ADDRESS qualifier « 8-6, CD-47, CD-83, CD-250 
/AFTER qualifier» CD—131, CD-188, CD~-200 
Aggregate 
DEPOSIT command « 4-17, 4-18, 11-7, 11-8, 
CD-61 
EXAMINE command « 4-17, 4—18, 11-6, 11-7, 
11-8, CD-85 
SET WATCH command « 3-19, 11-3 
ALLOCATE command 
debugging with two terminals * 9-6 
/ALL qualifier » CD—162 
CANCEL BREAK command « CD—17 
CANCEL DISPLAY command « CD-20 
CANCEL IMAGE command « CD-—22 
CANCEL MODULE command « CD-24 
CANCEL TRACE command « CD-30 
CANCEL WATCH command ¢ CD-34 
CANCEL WINDOW command ¢ CD-35 
DELETE command ¢ CD—57 
DELETE/KEY command « CD—59 
EXTRACT command « CD-101 
SEARCH command « CD~—121 
SET IMAGE command « CD-142 
SET MODULE command * CD-156 
SET TASK command ¢ CD-182 
SHOW DISPLAY command * CD—217 
SHOW KEY command « CD-223 
SHOW PROCESS command ¢ CD—235 
SHOW TASK command « CD—253 
SHOW WINDOW command * CD-262 
%AP * 4-23, D-4 
Apostrophe (’) 
ASCII string delimiter » 4-16 
instruction delimiter * 4-22 
/APPEND qualifier « CD—101 
Array type * 4-17 
vector register * 11-7 
/ASCIC qualifier » CD-61, CD-—85 
/ASCID qualifier > CD-62, CD-—85 
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/ASCII qualifier * CD-62, CD-86 
ASCII string type * 4-16, 4-28, CD-61, CD-85, 
CD-195 
/ASCIW qualifier * CD-62, CD-86 
/ASCIZ qualifier > CD-62, CD-86 
AST (asynchronous system trap) * 9-18 
CALL command « 9-18, CD-—10 
disabling * CD-68 
displaying AST handling conditions * CD—210 
enabling * CD-80 
SHOW CALLS command « 9-18 
AST-driven program 
debugging * 9-18 
Asterisk (*) 
HELP command * CD-107 
multiplication operator * D-7 
/AST qualifier * 9~18, CD—11 
At sign (@) 
contents-of operator « D~7 
execute-procedure command « 8—1, CD-—7 
SET ATSIGN command « CD-129 
SHOW ATSIGN command ¢ CD-211 
ATTACH command « 3-5, CD-9 
Attribute 
display * 7-3, 7-6, 7-10, 7-21, CD-—123, CD~—244 
window 
with DECwindows « 1-10 
AUTO window, DECwindows « 1-11 
/AW 
See /ASCIW quaiifier 
/AZ 
See /ASCIZ qualifier 


B 


Backslash (\ ) 
current value * 4-6 
global-symbol specifier * 5-10, CD-170, D-—7 
path name delimiter » 5—9, 6-4, D-7 
with DECwindows « 1-11, 1-28 
%BIN * 4-12, D-5 
/BINARY qualifier *4—-12, CD-81, CD-83, CD-86 
Bit field operator (<p,s,e>) * D—7 
/BOTTOM qualifier * CD—118 
/BRANCH qualifier > CD—17, CD-30, CD-131, 
CD-188, CD-265 
Breakpoint 
canceling * 3-17, CD-17 
defined * 3-9 
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Breakpoint (Cont.) 
delayed triggering of «3-14, CD-131 
displaying « CD-212 
DO clause * 3-14 
exception * 9-11, CD-—-130 
on activation (multiprocess program) * 10-14 
on termination (image exit) * 10-14 
on vector instruction * 11-3 
predefined * 9-11 
setting «3-9, CD-130 
source display at» 6—7 
WHEN clause « 3-14 
with DECwindows « 1—24 
/BRIEF qualifier * CD—-223, CD-236 
Built-in symbol « C-6, D-3 
/BYTE qualifier» CD-62, CD-—86 


C 


/CALLABLE_EDT qualifier » CD-139 
/CALLABLE_LSEDIT qualifier » CD—139 
/CALLABLE_TPU qualifier > CD-—139 
CALL command ¢ 8-11, CD~—10 
and ASTs « 9-18, CD-10 
multiprocess program « 10-6 
vectorized program « 11-24 
with DECwindows « 1-8 
%CALLER_TASK * D—11 
Call frame 
field and buttons in main window 
with DECwindows « 1-9, 1-21, 1-22, 1-28 
/CALL qualifier» CD-17, CD-30, CD-131, CD—188, 
CD-265 
/CALLS qualifier» CD-156, CD-253 
Call stack 
See also Scope 
displaying * 2-15, 9-13, CD-214, CD-—248 
with DECwindows « 1-24 
used to contro! instruction display * 7~10, CD-170 
with DECwindows « 1-9, 1-22 
used to control source display * 7-7, CD—170 
with DECwindows « 1-9, 1-271 
used to control symbol search «5-10, CD—170 
with DECwindows « 1-9, 1-28 
CANCEL ALL command * CD-15 
CANCEL BREAK command « 3-17, CD—17 
CANCEL DISPLAY command « 7-13, CD-—20 
CANCEL IMAGE command « 5—15, CD—22 
CANCEL MODE command * CD~23 
CANCEL MODULE command « 5-7, CD—24 





CANCEL RADIX command « 4-12, CD—26 
CANCEL SCOPE command ¢ 5-12, CD-27 
CANCEL SOURCE command « 6-3, CD-28 
CANCEL TRACE command « 3-17, CD-30 
CANCEL TYPE/OVERRIDE command « 4-26, CD-33 
CANCEL WATCH command « 3-17, CD-34 
CANCEL WINDOW command « 7-16, CD-35 
Case sensitivity » 9-10 
Catchall handler « 9-14 
Circumflex (*) * 4-8, 4-13, D-5 
/CLEAR qualifier * CD-70 
Code 
see Instruction 
Code address expression 
selecting from window 
with DECwindows « 1-23 
Colon (:) 
range delimiter * 4-18, 11-4, 11-6, 11-7, CD-85 
Command format 
debugger * CD-3 
Command interface 
COMMAND box, DECwindows « 1-20, 1-28 
debugger « 2-1 
with DECwindows « 1-28, 1-35, 1-36 
Command procedure 
See also Initialization file, debugger 
debugger « 8-1 
default directory for * CD-129, CD-211 
displaying commands in * CD-159 
exiting  CD-7, CD-94, CD-112 
invoking * CD—7 
log file as * 8-5 
passing parameters to «8-2, CD44 
recreating displays with « 7-24, CD-101 
with DECwindows « 1-29 
/COMMAND qualifier * 8-6, CD—47 
Comment 
format » CD-4 
Compiler 
compiler generated type » 4-4 
/DEBUG qualifier «5-2, 6-1 
with DECwindows « 1~2 
/LIST qualifier « 6-1 
/NOOPTIMIZE qualifier * 5-2, 9-1 
with DECwindows « 1—2 
Condition handler 
debugging * 9-11 
/CONDITION_VALUE qualifier » CD-81, CD-86 
CONNECT command « 10-4, 10-15, CD-36 
Contents-of operator * 4-7, 4-20, D-—7 
CTRL/C + 2-8, 10-5, 10-10, CD-38 
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CTRL/W - CD-40, CD-73 
CTRL/Y + 2-8, 3-4, 3-5, 10-14, CD—41 
with DECwindows « 1-34 
CTRL/Z + 3-5, CD—40 
%CURDISP » C—-7 
%CURLOC « 4-8, 4—13, D-5 
Current 
display * 7-3, 7-21, CD-123, CD-—244 
entity - 4-8, 4-13, 4-20, D-5 
with DECwindows « 1-9 
image * 5-15, CD-142, CD-—222 
language * 4-10, CD-145, CD—226 
location «2-11, 6-4, 6-5, 7-6, 7-10 
with DECwindows « 1-21, 1-22 
radix «4-11, CD-168, CD-240 
scope ¢ 5—11, CD—170, CD-241 
type * 4-25, CD-195, CD-—259 
value * 4-6, D-5 
Current entity 
field and buttons in main window 
with DECwindows « 1-9 
/CURRENT qualifier «5-12, CD-170 
%CURRENT_SCOPE_ENTRY « D-11 
%CURSCROLL « C-—7 
%CURVAL « 4-6, D--5 


D 


Data type 

See Type 
/DATE_TIME qualifier e CD-62, CD—86 
DBGS$DECW$DISPLAY 

with DECwindows ¢ 1-34, 1-35, 1-37, D—1 
DBGS$INIT « 8-4, D—-1 





DBGS$INPUT ¢ 9-6, D-1 


with DECwindows « 1-36 
DBG$O0UTPUT «9-6, D~1 

with DECwindows * 1-36 
DBG$PROCESS ¢ 2-6, 10-1, 10-10, D-1 

with DECwindows « 1-3, 1-30 
DEBUG command « 3-4, 10-14, CD-41 

with DECwindows « 1-34 
Debugger 

command interface * 2—1 

with DECwindows « 1-28, 1-35, 1-36 
DECwindows interface 1-1 _ 
displaying command interface on other terminal « 


with DECwindows « 1-36 
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Debugger (Cont.) 
displaying DECwindows interface on other 
workstation * 1-35 
invoking from DECwindows FileView window « 
1-33 
invoking over DECnet link » 3-1 
Debugger command 
dictionary * CD-3 
format * CD-3 
repeating » CD—103, CD-115, CD-—277 
summary * 2—27 
with DECwindows « 1-28, 1-35, 1-36 
Debugging configuration 
See also Debugger 
default «2-6, 10—10 
with DECwindows « 1-3 
multiprocess « 10-1, 10-10 
with DECwindows « 1-30 
/DEBUG qualifier «3-1, 5-2, 5-4, 6-1 
shareable image * 5—12 
with DECwindows « 1-2 
Debug symbol table 
See DST 
%DEC * 4—12, D-5 
/DECIMAL. qualifier * 4-12, CD-81, CD-83, CD-86 
DECLARE command « 8-2, CD-44 
DECnet 
debugging over * 3-1 
DECwindows 
debugger interface « 1-1 
debugging DECwindows application « 1-35 
DECwindows interface 
debugger « 1—1 
displaying on other workstation * 1-35 
/DEFAULT qualifier » CD-86 
DEFINE command « 8-6, CD-—47 
displaying default qualifiers for» CD-216 
setting default qualifiers for * CD-—138 
/DEFINED qualifier - CD-250 
DEFINE/KEY command « 8-8, CD-—50 
DEFINE/PROCESS_GROUP command ¢ 10-13, 
CD-54 
DELETE command « 8-6, CD—57 
DELETE/KEY command « 8-9, CD-59 
Deposit 
DEPOSIT command « 4-3, CD-61 
instruction * 4-22, 11-13 
with DECwindows « 1-26 
into address ¢ 4—25 
with DECwindows « 1-26 
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Deposit 
into register * 4~—23, 11-4 
with DECwindows « 1-26 
into variable * 4—3, 4—15 
with DECwindows « 1-25 
into vector register « 11-4 
vector instruction « 11-13 
DEPOSIT command « 4-3, CD-61 
/DIRECTORY qualifier * CD—224 
/DIRECT qualifier * CD-—250 
DISABLE AST command « 9-18, CD-68 
Display, debugger, screen mode 
See also Source display, Instruction, Window 
attribute * 7-3, 7-21, CD-123, CD-244 
canceling « 7-13, CD-20 
contracting * 7-14, CD-98 
creating * 7-14, CD-69 
current * 7-3, 7-21, CD-123 
default configuration * 7-2, 7-4 
defined * 7-2 
DO display * 7-17, 11-24 
expanding * 7-14, CD-98 
extracting * 7-24, CD-101 
hiding * 7-13, CD—71 
identifying * 7-13, CD-217 
instruction display (INST) * 7-8, 7-18 
kind « 7-3, 7-16, C—1 
list » 7-3, CD-217, C-6 
moving * 7-13, CD—110 
output display (OUT) + 7-7, 7-19 
pasteboard « 7-3, CD-74 
predefined * 7-4, C-3 
process specific * 10-16 
prompt display (PROMPT) « 7-7 
register display (REG) « 7-10, 7-19, 11-24 
removing * 7-13, CD-73 
saving * 7-24, CD~-116 
scrolling « 7-12, CD-118 
selecting * 7-21, CD-123 
showing * 7-13, CD-69 
window * 7-2, 7-15, C—7 
DISPLAY command « 7-12, 7-14, CD-69 
DO clause 
example « 3-14 
exiting * CD-94, CD-112 
format « CD—4 
DO command « 10-6, 10-7, CD-76 
DO display * 7-17, C—1 
/DOWN qualifier » CD-98, CD-110, CD-118 
DST (debug symbol table) 
creating * 5—4 


DST (debug symbol table) (Cont.) 


shareable image * 5-14 

source line correlation * 6—1 
Dynamic mode « CD—152 

image setting * 5-14 

module setting * 5—7 

with DECwindows « 1-27 

Dynamic process setting * 10-8, CD-162 
Dynamic prompt setting * 10-2, CD-—165 
/DYNAMIC qualifier > CD-71, CD-162, CD-236 
/D_FLOAT qualifier - CD-62, CD-86 


E 


/ECHO qualifier * CD~51 
EDIT command « CD-78 
/EDIT qualifier - CD-28, CD-176, CD-246 
ENABLE AST command « 9-18, CD-80 
/ERROR qualifier « 7-22, CD~123 
Evaluate 
memory address * 4-13, CD-83 
with DECwindows « 1-26 
EVALUATE/ADDRESS command « 3-13, 3-20, 4-13, 
CD-83 
EVALUATE command « 4—5, CD-81 
Event facility, setting « CD-141, CD-220 
Eventpoint 
See Breakpoint, Tracepoint, Watchpoint 
/EVENT qualifier * 3-16, CD-17, CD-30, CD-—131, 
CD-188 
Examine 
address * 4-25 
with DECwindows « 1-26 
EXAMINE command « 4—2, CD-—85 
instruction « 4-20, 11-9 
with DECwindows « 1-26 
register *4—23, 11-4 
with DECwindows « 1-26 
using vector mask * 11-13 
variable * 4-2, 4-15 
with DECwindows « 1-25 
vector address expression * 11-18 
vector instruction * 11-9 
vector register « 11-4 
Examine button 
with DECwindows « 1-9 
EXAMINE command « 4-2, CD—85 
EXAMINE/INSTRUCTION command « 4-20, 7-10, 
C-5 | 
EXAMINE/OPERANDS command « 4-20, 11-9 
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EXAMINE/SOURCE command « 6-5, 7-6, C—4 
Exception 


See also Vector exception 
debugging « 9-11 
Exception breakpoint or tracepoint 
canceling « 9-12, CD-17, CD-30 
qualifying * 9-16, D~10 
resuming execution at «9-12 
setting * 9-12, CD~131, CD—188 
Exception handler 
debugger as * 3-22 
debugging * 9-11 
/EXCEPTION qualifier «9-11, CD-17, CD-30, 
CD-131, CD-188, CD-265 
Exclamation point (!) 
comment delimiter » CD—4 
log file « 8-5 
%EXC_FACILITY * 9-16, D-10 
%EXC_NAME * 9-16, D—10 
%EXC_NUMBER « 9-16, D-10 
%EXC_SEVERITY * 9-16, D—10 
Execution 
as controlled by debugger « 3-22 
discrepancies caused by debugger « 3-24 
interrupting with CTRL/C « 2-8 
interrupting with CTRL/Y « 3-4 
with DECwindows « 1-34 
interrupting with Stop button 
with DECwindows « 1-9, 1-21 
monitoring with SHOW CALLS command « 2-15, 
CD-214 
monitoring with tracepoint «3-10, CD-187 
with DECwindows « 1-24 
multiprocess program * 10-6, CD-152 
resuming after exception break « 9-12 
starting or resuming with CALL command « 8-11, 
11-24, CD-10 
starting or resuming with GO command « 2-13, 
~CD-—105 
with DECwindows « 1-24 
starting or resuming with STEP command ¢ 3-7, 
CD-265 
with DECwindows « 1-24 
suspending with breakpoint * 3~9, CD-—130 
with DECwindows « 1-24 
suspending with exception breakpoint * 9-12, 
CD-131 
suspending with watchpoint «3-17, 10-17, 
CD-—200 
with DECwindows « 1-25 
vectorized program « 11-2 
SEXIT * 9-17 
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EXIT command ¢ 3-5, 9-17, CD-94 
multiprocess program « 10-9, 10-10 
with DECwindows « 1-21 

Exit handler 
debugging * 9-17, CD-—94 

~ executing «3-5, CD-94 

with DECwindows « 1-21 
execution sequence of * 9-17 
identifying * 9-18, CD-—221 

EXITLOOP command « 8-11, CD—97 

/EXIT qualifier * CD-78 

EXPAND command « 7-14, CD-98 

Expression 


See Address expression, Language expression 
EXTRACT command « 7-24, CD-101 


F 


File 
See Command procedure, Log file, Initialization 
file, Source file 
Final handler * 9-14 
/FLOAT qualifier > CD-62, CD-86 
/FMASK qualifier « 11-13, CD-88 
FOR command « 8—10, CD-—103 
%FP * 4-23, D-4 
/FULL qualifier * CD-236, CD-253 


G 


General register 


See also Register 
/GENERATE qualifier * CD~71 
Global section watchpoint « 10-17 
Global symbol 

See Symbol 
Global symboi table 

See GST 
Go button 

with DECwindows « 1-9 
GO command « 2-13, CD-—105 

multiprocess program * 10-6 

with DECwindows « 1-24 
GST (global symbol table) 

creating * 5—4 

shareable image * 5-13 
/G_FLOAT qualifier » CD-62, CD-86 
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H 


Handler 
condition * 9-14 
Help 
online * 2—8, CD—107 
for debugger messages * 2-8, CD-5 
with DECwindows « 1-19 
HELP command «2-8, CD—107 
%HEX * 4-12, D-5 
/HEXADECIMAL qualifier » 4-12, CD-81, CD-83, 
CD-87 
/HIDE qualifier » CD—71 
/HOLD qualifier * 10-3, 10-7, CD-162, CD-182, 
CD-236, CD-—253 
Hyphen (-) 
line-continuation character « CD—4 
subtraction operator * D~7 
/H_FLOAT qualifier» CD-63, CD-87 


Identifier 
search string * 6-7 
/IDENTIFIER qualifier * 6-7, CD-121 
IF command « 8-10, CD-—109 
/IF_STATE qualifier » 8-9, CD-51 
Image 
See also Shareable image 
privileged, securing * 5-6 
shareable, debugging * 5-12 
with DECwindows « 1-30 
indirection operator 
See Contents-of operator 
Initialization 
debugging session « 3-1, 9-8 
with DECwindows « 1—5 
Initialization code * 9-10 
with DECwindows « 1—5 
Initialization file 
See also Command procedure, debugger 
debugger * 8-4, D—1 
with DECwindows « 1-29 
Input, debugger 
DBG$DECWS$DISPLAY 
with DECwindows « 1-35, D—1 
DBG$INPUT « 9-6, D-1 
with DECwindows * 1-36 


ANPUT qualifier * 7~22, CD-123, CD—168, CD-263 
Instruction 
See also Vector instruction 
depositing * 4—20, 4—22 
with DECwindows « 1-26 
display (INST) * 4-20, 7-8, 10-16, C—-5 
for routine on call stack * 7-10, CD-170 
with DECwindows « 1-9, 1-11, 1-22 
display kind « 7-18, C—1 
EXAMINE/INSTRUCTION command ¢ 4-20, 7-10, 
C-5 
EXAMINE/OPERANDS command « 4-20 
examining * 4-20, 7-8 
with DECwindows « 1—22, 1—26 
operand « 4—20, CD-87, CD-153 
optimized code « 7-8, 9-1 
with DECwindows « 1-11, 1-22 
selecting from DECwindows window « 1-23 
SET SCOPE/CURRENT command « 7-10, 
CD-170 
window (INST), DECwindows « 1-11, 1-22 
/AINSTRUCTION qualifier * 7-10, 7-22, CD-18, 
CD-31, CD-63, CD-87, CD-123, CD-132, 
CD-188, CD-—265 
%INST_SCOPE « 7-18, C-5 
Integer type * 4—15, 4-25, 4-27 
Interrupt 
debugging session « 3-5 
execution of command « 2-8, CD-38 
with DECwindows « 1--21 
execution of program * 2—8, 3-4, 10-6, 10-10, 
10-14, CD-36, CD-38, CD-41, CD-152 
with DECwindows « 1-21 
/INTO qualifier »e CD-132, CD-189, CD-200, CD-265 
Invoking 
debugger « 2—5, 2-7, 3-1, 10-1, 10-14, CD-41 
with DECwindows « 1-2, 1-4, 1-33 
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/JSB qualifier *3-14, CD—132, CD-189, CD-265 


K 


Key definition 
creating * 8-8, CD-—50 
debugger predefined « B—1 
with DECwindows « 1-31 
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Key definition (Cont.) 
debugger predefined, multiprocess * 10-17 
deleting * 8-9, CD-59 
displaying * 8-9, CD-223 
Keypad mode « 8-8, CD-50, CD-153, CD-223, B—1 
Key state «8-9, CD-50, CD-223, B—1 


L 


%LABEL ¢ 3-11, D—7 
Language 
current * 4—10, CD-—145 
identifying * CD-226 
multilanguage program * 9-7 
with DECwindows « 1-29 
setting ° 4-10, CD-145 
support by debugger « E—1 
with DECwindows « 1~2 
Language expression 
compared to address expression « 4-8 
with DECwindows « 1-23 
DEPOSIT command ¢ 4—3, CD-61 
EVALUATE command «4-5, CD-81 
evaluating * 4—5 
with DECwindows « 1—27 
FOR command « 8-10, CD-—103 
IF command * 8-10, CD—109 
REPEAT command « 8-11, CD-115 
WHEN clause « 3-14 
WHILE command ¢ 8-11, CD—277 
Language-Sensitive Editor » CD—78 
Last-chance handler * 9-14 
LAT terminal 
debugging using two * 9-7 
/LEFT qualifier» CD-98, CD-110, CD-118 
Lexical function 
See Built-in symbol 
LIBSINITIALIZE *« 9-10 
%LINE * D—7 
EXAMINE command ¢ 4—20 
EXAMINE/SOURCE command « 6-5 
GO command « CD—105 
SET BREAK command « 3-11 
SET TRACE command * 3-11 
STEP command « 3-7 
Line mode * CD-153 
Line number 
See also %LINE 
selecting from DECwindows window « 1-23 
source display * 6-1, 6-3, 6—5 
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Line number 
source display (Cont.) 
with DECwindows « 1-10 
traceback information * 2-15, 5-3 
treated as symbol « 5-9 
/LINE qualifier * 3-14, CD-18, CD-31, CD-87, 
CD-—132, CD-189, CD-—266 
LINK command « 5—4, 6-2 
shareable image * 5-12 
with DECwindows « 1-2 
/LIST qualifier » 6—1 
/LOCAL qualifier » 8-6, CD-47, CD-57, CD-250 
Local symbol 
See Symbol 
/LOCK_STATE qualifier » CD-51 
Log file 7 
as command procedure « 8-5 
debugger * 8-5, CD—159 
with DECwindows « 1-29 
name of «8-5, CD-147, CD-227 
Logical name 
debugger * D—1 
Logical predecessor « 4—8, 4—13, 4-20, D-5 
with DECwindows « 1-9 
Logical successor * 4—8, 4-13, 4-20, D-5 
with DECwindows « 1-9 
/LOG qualifier * CD-51, CD-59 
/LONGWORD qualifier » CD-63, CD-87 


Margin 
source display « 6-9, CD—148, CD-—228 
/MARK_CHANGE qualifier « CD-71 
Mask 
EXAMINE/FMASK command « 11-13 
EXAMINE/TMASK command « 11-13 
masked vector operation * 11-6, 11-10, 11-13, 
11-14 
register, VMR « 11-6, 11-10, 11-13, 11-14 
Memory 
effect of debugger « 3-24 
Message 
debugger « 2-8, CD-5 
with DECwindows « 1-20 
MicroVAX 
See Workstation 
Mode 
CANCEL MODE command « CD-23 
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Mode (Cont.) 
SET MODE [NO]DYNAMIC command ¢ 5-7, 5-14, 
CD-152 
SET MODE [NO]JG_FLOAT command « CD-—152 
SET MODE [NOJINTERRUPT command « CD-152 
SET MODE [NO]KEYPAD command ¢ 8-8, 
CD-153 
SET MODE [NOJLINE command « CD-153 
SET MODE [NOJOPERANDS command ¢ 4-20, 
CD-153 
SET MODE [NO]JSCREEN command « 7-1, 
CD-154 
SET MODE [NO]SCROLL command « CD-154 
SET MODE [NO]JSEPARATE command ¢ 9-5, 
CD-154 
with DECwindows « 1-36 
SET MODE [NO]JSYMBOLIC command « 4-14, 
CD-—154 
SHOW MODE « CD-—230 
/MODIFY qualifier e CD-132, CD-189 
Module « 2-6 
See also Shareable image 
canceling * 5-7, CD-24 
information about * 5-7, CD-231 
setting 5-6, CD-156 
with DECwindows « 1-27 
traceback information * 5-3 
with DECwindows « 1-2 
/MODULE qualifier » CD-28, CD-171, CD-176 
MOVE command « 7-13, CD-—110 
Multilanguage program 
debugging * 9-7 
with DECwindows « 1-29 
Multiprocess program 
CALL command « CD-10 
CONNECT command « 10-4, 10-15, CD-36 
controlling execution * 10-6 
DBG$PROCESS ° 10-10 
debugging « 10-1 
with DECwindows « 1-9, 1-30 
DEFINE/PROCESS_GROUP command ¢ CD-54 
DO command « 10-5, CD-76 
EXIT command « 10-9, 10-10, CD-94 
with DECwindows « 1-21 
global section watchpoint « 10-17 
GO command « 10-6, CD-105 
QUIT command « 10-9, 10-10, CD-112 
with DECwindows « 1-21 
screen mode features * 10-16 
SET MODE [NOJINTERRUPT command « 10-7, 
CD-152 
SET PROCESS command « 10-7, 10-8, CD—161 


Multiprocess program (Cont.) 


SHOW PROCESS command « 10-3, CD-235 
Specifying processes « 10-12 

STEP command « 10-6, CD-265 

system requirements * 10-19 

with DECwindows « 1-9, 1—30 


N 


%NAME + D—4 
Network 
debugging over « 3-1 
%NEXTDISP * C—7 
%NEXTINST * C—7 
%NEXTLOC « 4-8, 4-13, D-5 
Next location 
See Logical successor 
%NEXTOUTPUT « C-—7 
/NEXT qualifier * 6-6, CD-121 
%NEXTSCROLL « C-7 
%NEXTSOURCE + C-7 
%NEXT_PROCESS « 10-12 
%NEXT_ SCOPE_ENTRY « D—11 
%NEXT_TASK * D-11 
Nonstatic variable « 3-20, 4-1 
with DECwindows « 1-25 
/NOOPTIMIZE qualifier * 2-6, 5-2, 9—1 
with DECwindows « 1-2 
NOP (No Operation) instruction * 4-23 


O 


Object module * 5-3, 6-1 
%OCT * 4—12, D—5 
/OCTAL qualifier «4-12, CD-81, CD-83, CD-87 
/OCTAWORD qualifier » CD-63, CD-87 
Operand 

instruction * 4-20, CD-87, CD-153 

vector instruction * 11-6, 11-9 
/OPERANDS qualifier * 4-20, 11-9, CD-87, CD~153 
Operator | 

address expression * D—7 

language expression * E—1 
Optimization 

effect on debugging * 2-6, 5-2, 7-8, 9-1 

with DECwindows « 1-2, 1-10, 1-11 

/OPTIMIZE qualifier * 2-6, 5-2, 9-1 

with DECwindows « 1-2 
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/OPTIONS qualifier * 5-12 
Output 
configuration, displaying * 8-2, 8-6, CD-234 
configuration, setting * 8-2, 8-6, CD-—159 
debugger, DBG$SDECW$DISPLAY 
with DECwindows « 1-35, D-1 
debugger, DBGSOUTPUT « 9-6, D-1 
with DECwindows « 1-36 
display (OUT) * 7-7, C-4 
with DECwindows « 1-10 
display kind « 7-19, C—1 
window (OUT), DECwindows « 1-10 
/OUTPUT qualifier » 7-22, CD-124, CD-168, CD~263 
/OVER qualifier» CD-133, CD-189, CD-201, 
CD-266 
/OVERRIDE qualifier * 4-26, CD-26, CD-33, 
CD-168, CD-196, CD-240, CD-259 
Override type * 4-26 


p 


/PACKED qualifier » CD-63, CD-88 
%PAGE * C-6 
/PAGE qualifier * 7-24, CD—185 
Parameter 
debugger command procedure « 8-2, CD-44 
%PARCNT « 8-2, D-5 
Pasteboard * 7-3 
Path name 
abbreviating * 5-10 
numeric * 5-10 
relation to symbol « 5—9 
with DECwindows « 1-11 
syntax * 5-9 
to specify scope * 5-8, 5—9 
with DECwindows « 1-28 
%PC 
See PC 
PC (program counter) 
built-in symbol (%PC) « 4-23, D-4 
content of * 2-12, 4~20 
EXAMINE/INSTRUCTION command ¢ 7-10, 7-18 
EXAMINE/OPERANDS command « 4-20, 11-9 
EXAMINE/SOURCE command «6-5, 7-6, 7-20, 
7-23 
examining * 4-20, 11-9 
with DECwindows « 1-26 
scope ¢ 5-8 
SHOW CALLS display * 2-15, CD—214 
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Index 


Period (.) 
contents-of operator « 4-7, 4-20, D-7 
current entity *4—8, 4-13, D—5 
Pointer type * 4-19 
/POP qualifier» CD-71, CD-166 
Pop-up menu 
with DECwindows « 1-12 
Predecessor 
See Logical predecessor 
/PREDEFINED qualifier e CD-15, CD-18, CD-31, 
CD-—212, CD-257 
Previous location 
See Logical predecessor 
%PREVIOUS_PROCESS « 10-12 
%PREVIOUS_SCOPE_ENTRY »* D—11 
%PREVLOC ¢ 4-8, 4-13, D-5 
Primary handler * 3-22, 9-14 
/PRIORITY qualifier * CD-183, CD-254 
Privilege 
allocate terminal * 9-7 
Process 
activation tracepoint, predefined » 10-14 
connecting debugger to * 10-4, 10-15, CD-36 
multiprocess debugging * 10-1 
with DECwindows « 1-9, 1-30 
termination tracepoint, predefined * 10-14 
/PROCESS qualifier * 10-6, 10-16, CD-71, CD-76 
/PROCESS_GROUP qualifier * 10-13, CD-54 
%PROCESS_NAME « 10-12 
%PROCESS_NUMBER « 10-12 
%PROCESS_PID * 10-12 
Program 
display kind * 7-21, C~1 
Program counter 
See PC 
/PROGRAM qualifier * 7-22, CD-—124 
Prompt 
COMMAND box, DECwindows « 1-28 
debugger (DBG>) « 2-7, 10-2, CD-165 
with DECwindows « 1-28, 1-35, 1-36 
display (PROMPT) * 7-7, C-4 
multiprocess program « 10-2 
/PROMPT qualifier - 7-22, CD-124 
Protection 
debugging with two terminals * 9-7 
of terminal « 9-7 
%PSL + 4-23, D-4 
PSL (processor status longword) * 4—24 
/PSL qualifier » CD-88 
/PSW qualifier » CD-88 
/PUSH qualifier » CD-—73 
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Q 


/QUADWORD qualifier * 11-7, 11-8, CD-63, CD-88 
QUIT command « 3-5, CD—112 

multiprocess program * 10-9, 10-10 

with DECwindows « 1-21 
Quotation mark (") 

ASCII string delimiter « 4—16 

instruction delimiter * 4-22 


R 


Radix 
canceling * CD-26 
conversion « 4-11, D-5 
current * 4-11, CD-—168 
displaying » CD-240 
multilanguage program * 9-9 
specifying «4-11, CD-168 
Range 
colon (:)* 4-18, 11-4, 11-6, 11-7, CD-85 
Real type * 4-15 
Record 
source line correlation * 6-1 
Record type * 4—18 
/REFRESH qualifier * CD—73 
Register 
See also Vector register 
built-in symbol « 4—23, D-4 
depositing into * 4—23 
with DECwindows « 1-26 
display (REG) * 7-10, C—5 
with DECwindows « 1-12 
display kind * 7-19, C—1 
examining * 4—23 
with DECwindows « 1-26 
PC 
See PC 
PSL * 4-24 
symbol « D—4 
symbolizing * 4-14, CD-271 
with DECwindows « 1-26 
variable * 3-20, 4—1 
with DECwindows « 1-25 
watchpoint « 3-20 
window (REG), DECwindows « 1-12 
/RELATED qualifier» CD-24, CD-156, CD-231 
/REMOVE qualifier * CD-73 





REPEAT command « 8-11, CD-115 
/RESTORE qualifier » CD-183 
Return key 
logical successor * 4-8, 4-13, D-5 
/RETURN qualifier » CD-133, CD-—190, CD-—266 
/RIGHT qualifier * CD-98, CD-110, CD-118 
Routine 
calling * 8—11, 11-24, CD-10 
call stack «2-15, 7-7, 7-10, CD-170, CD-214 
with DECwindows « 1-21, 1-22, 1-24, 1-28 
displaying instructions for, on call stack * 7-10, 
CD-170 
with DECwindows « 1-22 
displaying source code for, on call stack + 7-7, 
CD-170 
with DECwindows « 1-21 
EXAMINE/SOURCE command « 6—5 
multiple invocations of » 5-11, CD-170 
with DECwindows « 1-28 
selecting from DECwindows window « 1-23 
SET BREAK command « 3-11 
SET SCOPE command « CD-170 
SET TRACE command « 3-11 
SHOW CALLS command « 2-15 
traceback information * 5-3 
with DECwindows « 1-24 
RST (run-time symbol table) » 5-6 
and symbol search « 5-8 
deleting symbol records in * 5-7, CD-24 
displaying modules in «5-7, CD-231 
displaying symbols in * 5-9, CD-250 
inserting symbol records in * 5-6, CD-156 
shareable image * 5-14 
with DECwindows « 1-27 
RUN command « 3-1, 3-3, 5-4 
see also Execution 
shareable image * 5-14 
with DECwindows « 1-4 
Run-time symbol table 


See RST 


S 


SAVE command « 7-24, CD-116 
/SAVE_VECTOR_STATE qualifier * 11-24, CD—11 
Scalar type «4-15 
Scope 
built-in symbol « 7-4, 7-8, 7-18, 7-20, C-4, C-5, 
C-6, D-11 
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Scope (Cont.) 
canceling * 5-12, CD-—27 
current «5-11, CD-170 
default * 5-8, CD-27, CD-171, CD—241 
with DECwindows « 1-28 
displaying * 5-12, CD-241 
for instruction display * 7-10, CD—170 
with DECwindows « 1-9, 1—22 
for source display * 7-7, CD—-170 
with DECwindows » 1—9, 1-21 
for symbol search « 5-8, 5-11, CD-27, CD-170, 
CD-241 
with DECwindows « 1-9, 1-28 
PC + 5-8 
relation to call stack «5-10, 5-11, 5-12, 7-7, 
7-10, CD-170 
with DECwindows « 1-9, 1-21, 1-22, 1-28 
SEARCH command « 6-6, CD—120 
search list * 5-8, 5-11, CD—27, CD-170, CD-241 
with DECwindows « 1-9, 1-28 
SET SCOPE command « 5-11, 7-7, 7-10, 
CD-170 
setting ° 5-11, CD-170 
with DECwindows « 1-28 
specifying with path name « 5-9 
TYPE command « 6-4, CD-275 
vecior register + 11-2 
Screen display 
See Display, debugger, screen mode 
Screen management 
debugging DECwindows application « 1-35 
debugging screen-oriented program * 9-5 
with DECwindows « 1-36 
Screen mode « 7-1, CD-154 
multiprocess program * 10-16 
summary reference information « C-1 
Screen-oriented program 
debugging « 9-5 
with DECwindows « 1-35, 1—36 
Screen size 
displaying * 7-25, CD-256 
%PAGE, %WIDTH symbols * C-6 
setting * 7-24, CD-185 
/SCREEN_LAYOUT qualifier * CD-—101 
SCROLL command * 7-12, CD-—118 
Scroll mode * CD-154 
/SCROLL qualifier * 7-22, CD-124 
SEARCH command * 6-6, CD-—120 
displaying default qualifiers for »6—7, CD-243 
setting default qualifiers for » 6-7, CD-174 
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index 


Search list 
scope * 5-8, 5-11, CD-170, CD-241 
with DECwindows « 1-9, 1-28 
source file *6—2, CD-28, CD—176, CD-246 
Security 
image *5—6 
terminal * 9-7 
SELECT command « 7-21, CD-123 
Semicolon (;) 
command separator « CD—4 
SET ABORT_KEY command « 2—8, CD-127 
SET ATSIGN command « 8-2, CD—129 
SET BREAK command « 3-9, 6-7, 9-11, 11-3, 
CD-130 
SET DEFINE command « 8-6, CD-—138 
SET EDITOR command « CD-139 
SET EVENT_FACILITY command ¢ CD-141 
SET IMAGE command ¢ 5-15, CD-142 
effect on symbol definitions *» CD-48 
SET KEY command « 8-10, CD-144 
SET LANGUAGE command « 4-10, CD-145 
SET LOG command « 8-5, CD-147 
SET MARGINS command « 6-9, CD-148 
SET MAX_SOURCE_FILES command « 6-3, CD-151 
SET MODE command « CD-152 
SET MODE [NO]DYNAMIC command « 5-7, 5-14, 
CD-152 
SET MODE [NO]G_FLOAT command « CD-152 
SET MODE [NO]JINTERRUPT command « 10-6, 
CD-152 
SET MODE [NO]KEYPAD command « 8-8, CD-—153, 
B-1 
SET MODE [NO]LINE command * CD—153 
SET MODE [NOJOPERANDS command ¢ 4—20, 
CD-153 
SET MODE [NO]JSCREEN command « 7-1, CD-154 
SET MODE {[NO]JSCROLL command « CD—154 
SET MODE [NO]SEPARATE command « 9-5, 
CD-154 
with DECwindows « 1-36 
SET MODE [NO]SYMBOLIC command « 4-14, 
CD-154 
SET MODULE command « 5-7, 5-16, CD-156 
SET OUTPUT command « CD-159 
SET OUTPUT [NO]LOG command « 8-5, CD-159 
SET OUTPUT [NO]JSCREEN_LOG command « 8-6, 
CD-159 
SET OUTPUT [NO]TERMINAL command * CD-—159 
SET OUTPUT [NO]VERIFY command « 8-2, CD~159 
SET PROCESS command « 10-7, 10-8, CD—161 
SET PROMPT command « CD-—165 
SET RADIX command « 4-11, 9-9, CD-168 
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SET SCOPE command * 5—11, 6-4, 7-7, 7-10, 
CD-170 
SET SEARCH command « 6-7, CD-174 
SET SOURCE command « 6-2, CD-—176 
SET STEP command «3-8, 4—20, 6-7, 11-3, 
CD-179 
SET TASK command ¢ CD-182 
SET TERMINAL command « 7-24, CD-—185 
SET TRACE command « 3-10, 6-7, 9-11, 11-3, 
CD-187 
SET TYPE command « 4—25, CD-195 
SET TYPE/OVERRIDE command « 4-26, CD-195 
SET VECTOR_MODE command « 11-21, CD-198 
SET WATCH command « 3-17, 6-7, 11-3, CD-200 
SET WINDOW command « 7-16, CD-—207 
/SET_STATE qualifier * 8-10, CD-—51 
Shareable image 
See also Module 
CANCEL IMAGE command « 5-15, CD-22 
debugging * 5-12 
with DECwindows « 1-30 
SET BREAK/INTO command « 3-14, CD-133 
SET IMAGE command « 5-15, CD-142 
SET STEP INTO command «3-9, CD-—180 
SET TRACE/INTO command « 3-14, CD-190 
SET WATCH command « 3-22 
SHOW IMAGE command « 5-14, CD-222 
STEP/INTO command « CD—266 
/SHAREABLE qualifier * 5-12 
/SHARE qualifier «3-14, 5-16, CD-133, CD-190, 
CD-231, CD-266 
SHOW ABORT_KEY command « CD-209 
SHOW AST command « 9-18, CD-210 
SHOW ATSIGN command « 8-2, CD-211 
SHOW BREAK command « 3-11, CD-212 
SHOW CALLS command « 2-15, 3-4, 9-12, 9-18, 
CD-214 
SHOW DEFINE command « 8-6, CD-216 
SHOW DISPLAY command ¢ 7-13, CD-217 
SHOW EDITOR command « CD-219 
SHOW EVENT_FACILITY command * 3-16, CD-220 
SHOW EXIT_HANDLERS command « 9-18, CD-221 
SHOW IMAGE command « 5-14, CD-222 
SHOW KEY command « 8-9, CD-223 
SHOW LANGUAGE command « 4-10, CD-—226 
SHOW LOG command ¢ 8-6, CD-227 
SHOW MARGINS command « 6-9, CD-—228 
SHOW MAX_SOURCE_FILES command «6-3, 
CD-229 
SHOW MODE command « CD-230 
SHOW MODULE command ¢ 5-7, 5-16, CD-231 


SHOW OUTPUT command « 8-2, 8-6, CD-234 
SHOW PROCESS command « 10-3, 11-2, CD—235 
SHOW RADIX command « 4—11, CD-240 
SHOW SCOPE command « 5-12, CD-241 
SHOW SEARCH command « 6-7, CD-243 
SHOW SELECT command « 7-23, CD-—244 
SHOW SOURCE command « 6-2, CD—246 
SHOW STACK command « 9-13, CD-248 
SHOW STEP command « 3-8, CD—249 
SHOW SYMBOL command « 5-9, CD—250 
SHOW SYMBOL/DEFINED command « 8-6 
SHOW TASK command « CD—253 
SHOW TERMINAL command « 7-25, CD-256 
SHOW TRACE command « 3-11, CD~—257 
SHOW TYPE command « 4-26, CD-—259 
SHOW VECTOR_MODE command « 11-21, CD—260 
SHOW WATCH command « 3-17, CD-261 
SHOW WINDOW command ¢ 7-16, CD—262 
/SILENT qualifier - 3-14, CD-133, CD-190, CD—201, 
CD-266 
/SIZE qualifier * CD—73 
Slash (/) 
division operator * D—7 
SMG$ 
debugging screen-oriented program * 9-5 
Source code 
See Source display 
Source directory 
displaying * 6-2, CD-246 
search list * 6-2, CD—28, CD-176 
Source display * 2-9, 6-1, 7—1 
discrepancies in + 7-4, 9-1 
with DECwindows « 1-10 
display kind * 7-20, C—1 
EXAMINE/SOURCE command «6-5, 7-6, 7-20, 
C-4 | 
for routine on call stack * 7—7, CD-170 
with DECwindows « 1-9, 1-10, 1—21 
line-oriented * 6-3 
margins in * 6-9, CD-—228 
multiprocess program * 10-16 
not available * 2-11, 2-13, 6-1, 7-4, CD-176, C-4 
with DECwindows « 1-10, 1-21 
optimized code « 2-6, 5-2, 7-8, 9—1 
with DECwindows « 1-10 
SEARCH command « 6-6, CD-120 
SET BREAK command « 6—7 
SET SCOPE/CURRENT command « 7-7, CD—170 
SET STEP command « 6-7, CD-179 
SET TRACE command « 6-7 
SET WATCH command « 6-7 
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Source display (Cont.) 


SRC, predefined » 7-4, C—4 
with DECwindows « 1-10 
STEP command ¢ 6-7 
TYPE command ¢ 6-3, CD-275 
with DECwindows « 1-9, 1-10, 1-21 
Source file 
See also Source display 
correct version of » CD—176, CD-246 
defined * 6-2 
file specification * 6—2 
location * 6-2, CD-28, CD-176, CD-246 
maximum number « 6-3, CD-151, CD-—229 
not available *6~2, CD-—176 
Source line correlation » 6—1 
/SOURCE qualifier » 6-5, 6-8, 7-6, 7-23, CD-88, 
CD-124, CD-134, CD—190, CD-201, CD-267 
Source window 
See also Source display 
SRC, DECwindows « 1-10, 1-21 
%*SOURCE_SCOPE ¢ 7-20, C—4 
%SP ° 4-23, D-4 
SPAWN command « 3-5, CD-263 
SRC 
source display, screen mode * 7-4, C-4 
source window, DECwindows « 1-10, 1-271 
SS$_DEBUG condition » D-1 
Stack 
See also Call stack, Cail frame, Scope 
variable * 3-20, 4—1 
with DECwindows « 1-25 
ISTART_POSITION qualifier » CD-—139 
/STATE qualifier * 8-9, CD-60, CD-144, CD-224, 
CD-254 
ISTATIC qualifier » CD-201 
Static variable «3-20, 4—1 
STATISTICS qualifier > CD-254 
Step button — 
with DECwindows « 1-9 
STEP command « 3-7, 6-7, CD-—265 
and instruction-level debugging * 4—20 
displaying default qualifiers for « CD-249 
multiprocess program * 10-6 
setting default qualifiers for CD-179 
vectorized program « 11-3 
with DECwindows « 1-24 
Stop button 
with DECwindows « 1—9, 1—21 
STOP command « 3-5 
STRING qualifier * 6-7, CD-121 
String type * 4-16, 4-28 
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Successor 


See Logical successor 
/SUFFIX qualifier * 10-17, CD-20, CD-73, CD-98, 
CD-101, CD—110, CD-116, CD-118, CD—125, 
CD-165, CD-217 
Symbol 
See also DST, GST, RST, Scope 
ambiguity, resolving « 5-7 
with DECwindows « 1-28 
built-in * C-6, D-3 
compiler generated type * 4—4 
defining » 8-6, CD-48 
displaying * 5-9, 8-6, CD-48, CD-—250 
with DECwindows « 1-25 
global - 5-4, 5~10 
image setting «5-14 
local « 5—4 
module setting * 5-6 
with DECwindows ¢ 1-27 
not in symbol table * 5-6, 5-15 
with DECwindows « 1-27 
not unique * 5-9 
with DECwindows « 1-28 
relation to address expression * 4—4 
with DECwindows ¢ 1-23 
relation to path name « 5-9 
with DECwindows « 1-11 
search based on call stack «5-12, CD-170 
with DECwindows « 1-9, 1-28 
search conventions * 5-8, CD-—171 
with DECwindows « 1-9, 1—28 
SET SCOPE command « 5-11, CD—170 
shareable image * 5—14 
with DECwindows « 1-30 
show symbol 
with DECwindows « 1-25 
SHOW SYMBOL command « 5—9 
symbolic mode * 4—14, CD-154 
traceback information * 5-3 
universal «5—5, 5-12, 5-16 
vector register * 11-1 
Symbolic mode « 4~-14, CD-154 
/SYMBOLIC qualifier » 4-14, CD-88 
Symbolize 
address * 3-13, 4-14, CD-271 
with DECwindows « 1~26 
register * 4-14, CD-271 
with DECwindows « 1—26 
vector register * 11-1 
SYMBOLIZE command ¢ 3-13, 4-14, CD-271 
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Symbol record 


See Symbol 
Symbol table 
See DST, GST, RST 
Synchronization 
debugging vectorized program « 11-21, CD-198, 
CD-260, CD-273 
delivery of vector exception * 11-20, 11-21, 11-24 
SET VECTOR_MODE command « 11-21, CD-—198 
SHOW VECTOR_MODE command « 11-21, 
CD—260 
SYNCHRONIZE VECTOR_MODE command: 11-21, 
CD-273 
/SYSTEM qualifier * 3-14, CD-134, CD-190, CD-267 
System space 
SET BREAK command ¢ CD-134 
SET STEP command ° CD-—180 
SET TRACE command * CD-190 
STEP command * CD-—267 
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% TASK * D-11 
Tasking 
debugging * CD~182, CD~253 
with DECwindows « 1-30 
SET TASK command « CD-182 
SHOW TASK command « CD-253 
/TASK qualifier * CD-63, CD-88 
/TEMPORARY qualifier» CD~134, CD~191, CD-201 
Terminal 
for debugger input/output, separate - 9-5, CD—154 
using DECterm window « 1-36 
Terminal emulator 
See also Terminal 
Terminal screen size 
See Screen size 
/TERMINATE qualifier * 8-9, CD-51 
/TERMINATING qualifier * 10-14, CD-18, CD~31, 
CD-134, CD~-191 
Termination 
debugging session « 3-5, 10-9, CD-94, CD~112 
with DECwindows « 1-21 
execution of handlers at * 9-17 
multiprocess program « 10-9, 10-10, 10-14 
/TIME_SLICE qualifiers CD~183, CD-254 
/TMASK qualifier * 11-13, CD-88 
‘TOP qualifier « CD~119 
Traceback 
compiler option « 5-3 


Traceback (Cont.) 
link option * 5—4 
SHOW CALLS display » 2-15 
/TRACEBACK qualifier * 3-3, 5-4, 5-5 
shareable image « 5-13 
Tracepoint 
canceling * 3-17, CD-30 
defined * 3-10 
delayed triggering of * 3-14, CD-188 
displaying * CD—257 
DO clause « 3-14 
exception * 9-11, CD-187 
on activation (multiprocess program) * 10-14 
on termination (image exit) * 10-14 
on vector instruction « 11-3 
predefined * 10-14 
setting * 3-10, CD-187 
source display at * 6—7 
WHEN clause « 3-14 
with DECwindows « 1-24 
Transfer address ¢ 3-1, 9-8 
Type 
address expression * 4—4, 4-25 
array *4—17 
ASCII string * 4-16, 4-28 
compiler generated * 4—4, 4—15 
conversion, numeric * 4—7 
current * 4-25, CD-195, CD-259 
displaying * CD-259 
integer * 4-15, 4-27 
override * 4-26, CD-195 
pointer * 4-19 
real e 4—15 
record * 4-18 
scalar « 4—15 
SET TYPE command « 4-25, CD-195 
symbolic address expression « 4—4 
VAX instruction * 4-20 
vector register * 11-7 
TYPE command « 6-3, 7-6, CD-275 
Type override * 4-26, CD-33, CD-196, CD-259 
/TYPE qualifier «4-28, CD-63, CD-89, CD-251 


U 


Universal symbol! 


See Symbol 
/UP qualifier» CD-99, CD-111, CD—119 
/USER qualifier» CD-15, CD-18, CD-31, CD-212, 
CD-257 
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/USE_CLAUSE qualifier « CD-251 


V 


/VALUE qualifier 8-6, CD-—47 
Variable 
as override type * 4-28 
depositing into * 4—3, 4-15 
with DECwindows « 1-25 
examining * 4-2, 4-15 
with DECwindows « 1-25 
global section * 10-17 
initialized » 4—1 
nonstatic * 3-20, 4—1 
with DECwindows « 1-25 
optimized code * 9-1 
register * 3~20, 4—1 
with DECwindows « 1-25 
selecting from DECwindows window « 1-23 
stack local * 3-20, 4—1 
with DECwindows « 1-25 
static * 3-20 
uninitialized » 3-24 
watchpoint * 3-17, 10-17 
with DECwindows « 1-25 
Variable name 
address expression « 4-8 
with DECwindows « 1-23 
DEPOSIT command « 4—3. 
EXAMINE command « 4-2 
language expression * 4-6 
selecting from DECwindows window « 1-23 
SET WATCH command « 3-17 
VAX Language-Sensitive Editor » CD-78 
VAXstation 
See Workstation 
VAX Vector Instruction Emulation Facility 
See VVIEF 
%VCR 
See VCR 
VCR (vector count register) « 11-4, D-4 
Vector count register 
See VCR 
Vector exception 
delivery of * 11-20, 11-21, 11-24 
Vector instruction * 11-8 
CANCEL BREAK/VECTOR_INSTRUCTION 
command « 11-3, CD-—18 
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Index 


Vector instruction (Cont.) 

CANCEL TRACE/VECTOR_INSTRUCTION 
command « 11-3, CD-31 

delivery of vector exception * 11-20, 11-21, 11-24 

depositing * 11-13 

displaying « 11-8 

EXAMINE/OPERANDS command « 11-9 

examining « 11-9 

masked operation * 11-10, 11-15 

operand « 11-9 

replacing * 11-13 

SET BREAK/VECTOR_INSTRUCTION command 
° 11-3, CD~134 

SET STEP VECTOR_INSTRUCTION command ¢ 
11-3, CD-180 

SET TRACE/VECTOR_INSTRUCTION command 
¢ 11-3, CD-191 

STEP/VECTOR_INSTRUCTION command ¢ 11-3, 
CD-—267 

Vectorized program 

CALL/INOJSAVE_VECTOR_STATE command « 
11-24, CD-11 

controlling and monitoring execution * 11-2 

debugging « 11-1 
with DECwindows « 1-30 

delivery of vector exception * 11-20, 11-21, 11-24 

depositing into vector register * 11-4, 11-7 

depositing vector instruction * 11-13 

EXAMINE/FMASK command « 11-13 

EXAMINE/OPERANDS command « 11-9, CD-87 

EXAMINE/TMASK command « 11-13 

examining vector instruction * 11-9 

examining vector register * 11-4, 11-7 

masked operation « 11-6, 11-10, 11-13, 11-14 | 

obtaining information about « 11-2 | 

setting breakpoint + 11-3 

setting tracepoint * 11-3 

setting watchpoint * 11-3 

SET VECTOR_MODE command « 11-21, CD-198 

SHOW PROCESS/FULL command ¢ 11-2 

SHOW VECTOR_MODE command ° 11-21, 
CD-260 

specifying vector register * 11-4 

SYNCHRONIZE VECTOR_MODE command + 
11-21, CD-273 

synchronizing scalar and vector processors » 
11-21 

VO to V15 * 11-7 

VCR ¢ 11-4 

VLR « 11-5 | 

VMR ¢ 11-6, 11-10, 11-13, 11-14 

with DECwindows « 1—30 
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Vector length register 


See VLR 
Vector mask register 


See VMR 
Vector mode 
SET VECTOR_MODE [NO]SYNCHRONIZED 
command « 11-21 
SYNCHRONIZE VECTOR_MODE command * 
11-21 
Vector register 
See also Register 
built-in symbol « 11-4, D-4 
composite address expression « 11-18 
depositing into * 11-4, 11-7 
display, screen mode « 7-10, 7~17, 11-24 
examining ¢ 11-4, 11-7 
scope * 11-2 
V0 to Vi5° 11-7, D-4 
VCR- 11-4, D-4 
VLR 11-5, D-4 
VMR « 11-6, 11-10, 11-13, 11-14, D-4 
watchpoint * 11-3 
/VECTOR_INSTRUCTION qualifier * 11-3, CD-18, 
CD-31, CD-134, CD-191, CD-267 
Verity 
SET OUTPUT VERIFY command » CD-159 
Virtual memory address 


See Memory address 


_ Visible process « 10-2, 10-3, 10-8 


field and buttons in main window 
~ with DECwindows « 1-9 
/VISIBLE qualifier » CD-162, CD~-183, CD-236 
%VISIBLE_PROCESS « 10-12 
%VISIBLE_TASK * D~11 


— ANVLR 


See VLR 
VLR (vector length register) * 11-4, 11-5, D-4 
%VMR 
See VMR 
VMR (vector mask register) «11-4, 11-6, 11-10, 
11-13, 11-14, D-4 
VVIEF (VAX Vector Instruction Emulation Facility) 
SHOW PROCESS/FULL command « 11-2 


W 


/WAIT qualifier » CD-263 
Watchpoint 
aggregate * 3-19, 11-3 





Watchpoint (Cont.) 


canceling » CD-34 
defined * 3-17 
displaying * CD-261 
effect on execution speed * 3-20 
global section « 10-17 
multiprocess program « 10-17 
nonstatic (stack or register) variable » 3-20 
register ¢« 3-20 
setting * 3-17, CD-200 
shareable image * 3-22 
source display at « 6-7 
static variable » 3-20 
vector register * 11-3 
with DECwindows « 1-25 
WHEN clause 
example * 3-14 
format * CD—4 
WHILE command ¢ 8—11, CD—277 
%WIDTH * C-6 
/WIDTH qualifier * 7-24, CD-185 
Window 
See also Display, debugger, screen mode 
attribute, DECwindows « 1-10 
automatic (AUTO), DECwindows « 1-11 
default configuration, DECwindows « 1-4 
for debugger command interface 
DECwindows COMMAND box 1-20, 1-28 
DECwindows DECterm window « 1-36 
VWS window « 9-5, CD-154 
instruction (INST), DECwindows « 1-11, 1-22 
output (OUT), DECwindows « 1-10 
predefined, DECwindows « 1-9 
register (REG), DECwindows « 1-12 
screen-mode, creating definition for * 7-16, 
CD-207 
screen-mode, defined * 7—2 
screen-mode, deleting definition of - 7-16, CD-35 
screen-mode, identifying » 7-16, CD-262 
screen-mode, predefined * CD-262, C-—7 
screen-mode, specifying * 7-15 
— selecting address expression from, DECwindows » 
1-23 
source (SRC), DECwindows « 1-10, 1-21 
/WORD qualifier * CD-63, CD-—89 
Workstation 
debugger commands for (when using VWS) » 
CD-6 
debugger DECwindows interface for * 1-1 
debugging DECwindows application « 1-35 
debugging screen-oriented program 
using separate DECterm window « 1-36 


Index 


Workstation 


debugging screen-oriented program (Cont.) 
using separate VWS window « 9-5, CD—154 

popping debugger window (when using VWS) « 
CD-166 

separate, for debugger DECwindows interface « 
1-35 

separate debugger terminal-emulator window 
using DECwindows (DECterm) « 1-36 
using VWS « 9-5, CD-154 

terminal emulator screen size * 7-24, CD-—185 
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How to Order Additional Documentation 





Technical Support 


If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 
your electronic, telephone, or direct mail order. 


Electronic Orders 


To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud 
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location Call Contact 
Continental USA, 800-DIGITAL Digital Equipment Corporation 
Alaska, or Hawaii P.O. Box CS2008 

Nashua, New Hampshire 03061 
Puerto Rico 809-754-7575 Local Digital subsidiary 
Canada 800-267-6215 Digital Equipment of Canada 


Attn: DECdirect Operations KAOQ2/2 
P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 


International a Local Digital subsidiary or 
approved distributor 

Internal? annneaee USASSB Order Processing - WMO/E15 
or 


U.S. Area Software Supply Business 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 





1for internal orders, you must submit an Internal Software Order Form (EN-01740-07). 


Reader’s Comments VMS Debugger Manual 
AA-LA59SC—TE 





Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


I rate this manual’s: Excellent Good Fair Poor 


Accuracy (software works as manual says) 
Completeness (enough information) 
Clarity (easy to understand) 

Organization (structure of subject matter) 
Figures (useful) 

Examples (useful) 

Index (ability to find topic) 

Page layout (easy to find information) 


OOOOUOOOd 
OOOOOOOO 
NOOOOOUOo 
OOOOOO0UO 


I would like to see more/less 


What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 


Re) 
i 
© 


Description 








Additional comments or suggestions to improve this manual: 


I am using Version of the software this manual describes. 
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